Integration Guides

Direct API Integration

Full control over your payment flows with PayOS APIs

Overview

Direct API Integration with PayOS allows merchants to manage their own checkout screens and directly interact with PayOS APIs for payments. This approach offers full control over the user experience but requires the merchant to adhere to strict PCI-DSS compliance if sensitive card data is handled.

PCI-DSS Compliance Required

When using Direct API Integration, if your checkout process collects sensitive card details, you must be PCI-DSS certified. PayOS takes no responsibility for PCI violations if merchants improperly handle sensitive data. It is strongly recommended to outsource card data handling to our Secure Fields or Hosted Checkout to minimize compliance burdens.

How It Works

  1. Initiate a Payment Session: Create a payment initiation request to receive available payment methods from PayOS.

  2. Present Payment Options: Display the payment methods returned from PayOS on your custom checkout page.

  3. Capture and Process Payment Details: For card payments, you will need to capture card details and submit them securely to PayOS.

  4. Receive Payment Status Updates: Use webhooks to get real-time status updates for payments (e.g., authorized, declined).

Example: Payment Initiation Request

Initiating a payment with PayOS involves sending a request to the API to start a payment session. This session will provide you with the available payment methods that you can present to your customers.

1{
2  "amount": {
3    "value": 15000,
4    "currency": "NGN"
5  },
6  "customer": {
7    "email": "jane.doe@example.com",
8    "name": "Jane Doe"
9  },
10  "paymentMethods": ["card", "mobileMoney"],
11  "returnUrl": "https://merchant-site.com/success",
12  "cancelUrl": "https://merchant-site.com/cancel"
13}

Sample Response:

1{
2  "availableMethods": [
3    "card",
4    "mobileMoney"
5  ],
6  "sessionId": "abc123",
7  "expiresAt": "2024-10-18T14:00:00Z"
8}

Handling Card Payments

If the customer selects a card payment, the merchant must collect the card details securely. This requires PCI compliance to ensure the safety of sensitive card information.

If you collect card data directly, PCI certification is mandatory.

Example of a card payment submission:

$curl --request POST 'https://relay.api.payos.money/v1/payment/initiate' \
>--header 'Authorization: Bearer YOUR_API_KEY' \
>--header 'Content-Type: application/json' \
>--data-raw '{
>  "sessionId": "abc123",
>  "paymentMethod": {
>    "type": "card",
>    "cardNumber": "4111111111111111",
>    "expiryMonth": "12",
>    "expiryYear": "2026",
>    "cvv": "123"
>  }
>}'

Webhooks for Payment Status

PayOS will notify merchants via webhooks about the status of transactions. Make sure your server is set up to receive and handle these notifications.

Sample webhook payload:

1{
2  "event": "payment.authorized",
3  "data": {
4    "transaction_id": "txn_7890",
5    "status": "authorized",
6    "amount": 10000,
7    "currency": "NGN"
8  }
9}

Best Practices

  • Secure Payment Handling: Use tokenization where possible to avoid direct exposure to sensitive data.
  • Monitor API Usage: Ensure you are using the API efficiently to avoid rate limits.
  • Webhooks: Use webhooks for real-time updates on payment statuses.
  • Error Handling: Implement retry mechanisms for failed payments based on PayOS’s error codes.