Payments

Overview

A payment in PayOS refers to an individual attempt to process a charge against a specific payment method. Each payment attempt is a distinct operation that may succeed or fail independently. A single transaction can involve multiple payment attempts if retries are required.

For more details on initiating payments, refer to the Initiate Payment API.

Payment Attempts Explained

• Single Attempt: A simple one-time payment with no retries.
• Multiple Attempts: If a payment fails, PayOS automatically retries using alternative processors or payment methods (if configured).

Payment Attempt States:

1. Initiated: Payment request is sent to the payment processor.
2. Pending: Payment is under review or awaiting customer action (e.g., 3D Secure).
3. Authorized: Payment was approved but not yet captured.
4. Captured: Funds have been transferred from the customer.
5. Failed: Payment attempt failed, and PayOS may retry.
6. Refunded: Payment was refunded (full or partial).

For more information on payment states, see the Payment Response Schema.

Payment Methods

PayOS supports various payment methods, including:

• Credit/Debit Cards: Securely processed through tokenized transactions.
• Bank Transfers: Supports real-time and batch transfers.
• Mobile Money
• Digital Wallets: PayPal, Apple Pay, and others.

To view available payment methods, check the Get Available Payment Methods API.

Example Payment Payload

1
{
2
  "attemptId": "attempt_01",
3
  "transactionId": "1234567890",
4
  "processor": "Processor_A",
5
  "status": "captured",
6
  "amount": 10000,
7
  "currency": "USD",
8
  "paymentMethod": {
9
    "type": "card",
10
    "cardDetails": {
11
      "brand": "Visa",
12
      "last4": "4242",
13
      "expiryMonth": "12",
14
      "expiryYear": "2026"
15
    }
16
  },
17
  "timestamp": "2024-10-17T12:05:00Z"
18
}

For the full schema, refer to the Payment Initiate Request Schema.

Handling Payment Failures

PayOS retries failed payment attempts automatically. Merchants can configure retry rules to maximize success rates. In cases where retries are exhausted, a webhook notification will be sent to the merchant for further action.

For more details on handling failures, see the Error Response Schema.

Payment Capture and Refunds

• Capture: Payments must be captured to finalize the transfer of funds.
• Refunds: Payments can be refunded (partially or fully) based on merchant policies.

To refund a payment, use the Refund Payment API.

Security and Compliance

• PCI Compliance: Merchants must ensure PCI compliance when handling card data directly.
• 3D Secure Authentication: PayOS supports 3D Secure to reduce fraud.

For more information on security, refer to the Security and Compliance Documentation.

External Resources

For a complete list of API operations and schemas, visit the PayOS API Documentation.