Direct integration

In this approach no platform web application is involved and all steps of the incoming payment process must be integrated by the merchant application.

The first step of the process is to generate auth token to be able to pass all authorization checks for each necessary operation.

Note

NEW

The easiest way to verify you merchant account is to use our Integration DEMO Web Application to make necessary API calls and check our Payment Web Application flow.

Payment Options

In the second step, the customer must be challenged to select the appropriate payment option for the required transaction. Use the POST /payins/!availablePaymentOptions endpoint to list all available payment options.

This step is optional in cases where the merchant product configuration is not dynamic and the merchant is capable of taking the responsibility for using the correct payment method / payment operator selection.

Example CURL for requesting available payment options
curl -X POST 'https://api.sandbox.aopay.io/payins/!availablePaymentOptions' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'X-API-Version: 2' \
     -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIlBPU1QgL3BheWlucy8hYXZhaWxhYmxlUGF5bWVudE1ldGhvZHMiLCJQT1NUIC9wYXlpbnMvVFNULTExMjIzMyIsIkdFVCAvcGF5aW5zL1RTVC0xMTIyMzMiXSwiZXhwIjoxNjIyNjIzNjY5LCJqdGkiOiI5ZThhNDUwNC04MmRmLTQyY2QtOTQ3Ni03NjE2YjEzOTJlM2IiLCJpYXQiOjE2MjI2MjMwNjksInN1YiI6IllPVVJfTUVSQ0hBTlRfQ09ERSJ9.LkYT9qXY3hEixjoiUBKqxXnazWgfLCNg37RtdG_oXw0' \
     -d '{
           "money": {
             "amount": 100,
             "currencyCode": "IDR"
           }
         }'
Response of the example call
{
  "data": [
    {
      "paymentMethodCode": "VAPAY",
      "paymentOperators": [
        {
          "code": "BNK_000",
          "name": "Some real bank name"
        },
        {
          "code": "BNK_001",
          "name": "Some other real bank name"
        }
      ]
    }
  ]
}

Merchant Information

In the this step, the merchant can obtain its merchant information such as merchant channel name configured in our platform to display it on the payment flow UI.

This step is optional as usually merchant displays such information from theirs own configuration when using the direct API integration.

Use the GET /merchant-info endpoint to obtain the merchant information.

Example CURL for requesting a merchant channel information
curl -X POST 'https://api.sandbox.aopay.io/merchant-info' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'X-API-Version: 2' \
     -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIlBPU1QgL3BheWlucy8hYXZhaWxhYmxlUGF5bWVudE1ldGhvZHMiLCJQT1NUIC9wYXlpbnMvVFNULTExMjIzMyIsIkdFVCAvcGF5aW5zL1RTVC0xMTIyMzMiXSwiZXhwIjoxNjIyNjIzNjY5LCJqdGkiOiI5ZThhNDUwNC04MmRmLTQyY2QtOTQ3Ni03NjE2YjEzOTJlM2IiLCJpYXQiOjE2MjI2MjMwNjksInN1YiI6IllPVVJfTUVSQ0hBTlRfQ09ERSJ9.LkYT9qXY3hEixjoiUBKqxXnazWgfLCNg37RtdG_oXw0' \
Response of the example call
{
  "channelInfo": {
    "name": "YOUR_MERCHANT_CHANNEL_NAME"
  }
}

Payment request

The forth step involves creating the payment request itself via POST /payins/{idPayin} endpoint.

Example CURL for requesting payment
curl -X POST 'https://api.sandbox.aopay.io/payins/TST-112233' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'X-API-Version: 2' \
     -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIlBPU1QgL3BheWlucy8hYXZhaWxhYmxlUGF5bWVudE1ldGhvZHMiLCJQT1NUIC9wYXlpbnMvVFNULTExMjIzMyIsIkdFVCAvcGF5aW5zL1RTVC0xMTIyMzMiXSwiZXhwIjoxNjIyNjIzNjY5LCJqdGkiOiI5ZThhNDUwNC04MmRmLTQyY2QtOTQ3Ni03NjE2YjEzOTJlM2IiLCJpYXQiOjE2MjI2MjMwNjksInN1YiI6IllPVVJfTUVSQ0hBTlRfQ09ERSJ9.LkYT9qXY3hEixjoiUBKqxXnazWgfLCNg37RtdG_oXw0' \
     -d '{
           "paymentRequested": {
             "money": {
               "amount": 100,
               "currencyCode": "IDR"
             }
           },
           "paymentMethod": {
             "account": {
               "accountName": "Test account",
               "accountNumber": "11223344"
             },
             "paymentMethodCode": "VAPAY",
             "paymentOperatorCode": "BNK_000",
             "emailAddress": "customer@test.com"
           },
           "callbackUrl": "https://example.com/order-status-change",
           "returnUrl": "https://example.com?id=123"
         }'
Response of the example call
{
  "paymentRequested": {
    "money": {
      "amount": 100,
      "currencyCode": "IDR"
    }
  },
  "paymentMethodResponse": {
    "idPayin": "TST-112233",
    "paymentMethodCode": "VAPAY",
    "account": {
      "accountName": "Test account",
      "accountNumber": "11223344",
      "bankCode": "BNK_000",
      "bankName": "Some real bank name"
    },
    "money": {
      "amount": 100,
      "currencyCode": "IDR"
    },
    "expireAt": "2021-05-20T08:37:05.350Z",
    "reference": "VA1122334455",
    "returnUrl": "https://example.com?id=123"
  }
}

Payment completion

For some of the Payment methods your customer is required to provide us through your system with external payment reference. Therefore it is important to allow POST /payins/{idPayin}/!setExternalReference endpoint in the the authorization token - see generate auth token chapter. See list of our Payment methods to check which of them require to set the external payment reference and what are the format requirements.

Get payment status

The merchant is automatically notified of a payment status change via callback. This can be obtained anytime via our API.

Get payment customer account data

This can be obtained anytime via our API. Customer account data from request should be available shortly after payment creation. Customer account data from payment process should be available shortly after payment is successfully finished.