Transactions

Overview

A transaction in PayOS represents the complete lifecycle of a payment event. It encompasses all payment attempts, refunds, and adjustments associated with a specific payment flow. Understanding how PayOS handles transactions helps merchants track payments, retries, and outcomes.

Transaction Lifecycle

A transaction in PayOS can include multiple states as part of its journey. The following flow outlines the typical stages of a transaction when it makes use of the Hosted Checkout:

1. Initiation:

   • The transaction starts when a merchant sends an API call to PayOS to initiate a payment.
   • The initiation includes details like the amount, currency, payment methods, and customer information.
   • Use the /payment/initiate endpoint to start a transaction, ensuring you have a valid OAuth 2.0 access token for authentication.

   Example Request:

   1
   {
   2
     "amount": 15000,
   3
     "currency": "NGN",
   4
     "integrationType": "hosted",
   5
     "merchantReference": "ORDER12345",
   6
     "merchantLocation": "NG",
   7
     "redirectUrl": "https://merchant.com/redirect",
   8
     "brand": "merchant-brand-key",
   9
     "payerToken": "TOKEN_abcdef123456",
   10
     "payerDetails": {
   11
       "payerName": "Chinwe Okafor",
   12
       "payerEmailAddress": "chinwe.okafor@example.com",
   13
       "payerMobileNumber": "08012345678",
   14
       "payerLocation": "NG"
   15
     },
   16
     "paymentMethods": [
   17
       {
   18
         "type": "card",
   19
         "cardToken": "card-token-123456",
   20
         "restrict": false
   21
       }
   22
     ]
   23
   }

   Example Response:

   1
   {
   2
     "sessionId": "PAY_abcdef123456",
   3
     "paymentLink": "https://payos.money/pay/PAY_abcdef123456"
   4
   }

2. Payment Attempt:

   • After the transaction initiation, the merchant renders the hosted checkout to the payer.
   • The payer interacts with the hosted checkout, selecting one of the available payment methods. These methods are displayed based on configurable rules in the Rules Engine.
   • This stage involves the payer engaging with the checkout interface, selecting their preferred payment method, and entering any necessary details specific to that method.
   • In cases where the merchant is choosing to make use of direct integration, they will need to make use of the /payment/initiate endpoint with the integrationType set to direct and supply the paymentMethods array with the relevant payment method details.

3. Authorization:

   • The payment is authorized, and funds are reserved on the customer’s payment method. In some cases additional interaction may be required from the payer, and in these cases the Hosted Checkout will handle all interactions. In cases where a merchant is making use of direct integration, they might need to surface the userInteractionRequired URL to the payer.
   • Use the /payment/payments/{paymentId} endpoint to check the status of a payment.

   Example Request:

   $
   curl --request GET 'https://api.payos.money/api/v1/payment/payments/PAY_abcdef123456' --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

   Example Response:

   1
   {
   2
     "id": "PAY_abcdef123456",
   3
     "status": "AUTHORIZED",
   4
     "amount": {
   5
       "value": 15000,
   6
       "currency": "NGN"
   7
     }
   8
   }

4. Settlement:

   • Once authorized, the payment may move into a settled state, and funds are transferred to the merchant’s account.
   • The status can be checked using the same endpoint as for authorization.

   Example Response:

   1
   {
   2
     "id": "PAY_abcdef123456",
   3
     "status": "SETTLED",
   4
     "amount": {
   5
       "value": 10000,
   6
       "currency": "USD"
   7
     }
   8
   }

5. Refunds and Adjustments:

   • If necessary, refunds or adjustments can be processed using the /payment/payments/{paymentId}/refund endpoint.
   • Adjustments to the authorized amount can be made using the /payments/{id}/adjust-authorization endpoint.

   Example Refund Request:

   1
   {
   2
     "amount": 3500,
   3
     "orderId": "ORDER_987654321",
   4
     "reason": "Customer returned the item"
   5
   }

   Example Refund Response:

   1
   {
   2
     "id": "PAY_1234567890",
   3
     "status": "PARTIALLY_SETTLED",
   4
     "transactions": [
   5
       {
   6
         "id": "TRANS_123456",
   7
         "type": "refund",
   8
         "amount": 3500,
   9
         "date": "2024-03-20T09:30:00Z"
   10
       }
   11
     ]
   12
   }

6. Completion:

   • The transaction is completed once all payment attempts are successful or the payment is cancelled, and any necessary refunds or adjustments are processed.

Example Transaction Response

Here’s an example of a transaction response from the PayOS API:

1
{
2
  "transactionId": "txn_1048576",
3
  "status": "completed",
4
  "amount": {
5
    "value": 20000,
6
    "currency": "USD"
7
  },
8
  "attempts": [
9
    {
10
      "attemptId": "att_001",
11
      "processor": "Processor_A",
12
      "status": "failed",
13
      "timestamp": "2024-10-17T12:00:00Z"
14
    },
15
    {
16
      "attemptId": "att_002",
17
      "processor": "Processor_B",
18
      "status": "authorized",
19
      "timestamp": "2024-10-17T12:05:00Z"
20
    }
21
  ],
22
  "payer": {
23
    "email": "customer@example.com",
24
    "payerToken": "payer_12345"
25
  },
26
  "metadata": {
27
    "orderId": "ORD001",
28
    "description": "Payment for order ORD001"
29
  }
30
}

Monitoring and Reporting

PayOS provides detailed logs and dashboards to monitor transaction statuses and identify any issues in the payment flow. Merchants can use these tools to track retries, cancellations, and refunds within a transaction.

Authentication and Security

All transaction-related API calls require OAuth 2.0 authentication. Ensure that your access token is valid and included in the Authorization header of your requests. Refer to the Authentication Guide for more details on setting up and managing your OAuth 2.0 credentials.