Outgoing Payment

Before you start please check Outgoing Payment process flow:

Learn how to send outgoing payments (Payouts) to your customer account with our Payment gateway platform. You can make outgoing payments to your customers bank accounts.

To create a new outgoing payment the merchant application is responsible for requesting payment authorization token and then creating new outgoing payment request.

Authentication and authorization

Please refer to the Security section for a generic description of how the token can be obtained.

The fine-grained privileges must be used so that token cannot be misused by the user.

The POST /payouts/{idPayout} operation needs to be authorized in the token. The {idPayout} must be replaced with an actual Merchant Order ID unique ID generated by merchant.

Example CURL for generating auth token

curl -X POST 'https://api.sandbox.komopay.id/auth-tokens' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'X-API-Version: 2' \
     -d '{
           "merchantCode": "YOUR_MERCHANT_ID",
           "secret": "YOUR_MERCHANT_SECRET_KEY",
           "validitySecs": 600,
           "operations": [
             "POST /payouts/TST-223344",
             "GET /payouts/TST-223344"
           ]
         }'

Response of the example call

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIlBPU1QgL3BheW91dHMvVFNULTIyMzM0NCIsIkdFVCAvcGF5b3V0cy9UU1QtMjIzMzQ0Il0sImV4cCI6MTYyMjYyODQzOCwianRpIjoiZDdiOTI5YTktYTc2Yy00ZWE1LTkwZTUtZmY3YzNkZjE5NTRiIiwiaWF0IjoxNjIyNjI3ODM4LCJzdWIiOiJZT1VSX01FUkNIQU5UX0NPREUifQ.ULgCPXd01mc3JS6QOu6aZUSxw6eDCjpD_IehDkfoQes"
}

The Auth token above contains this payload:

Token payload

{
  "operations": [
    "POST /payouts/TST-223344",
    "GET /payouts/TST-223344"
  ],
  "exp": 1622628438,
  "jti": "d7b929a9-a76c-4ea5-90e5-ff7c3df1954b",
  "iat": 1622627838,
  "sub": "YOUR_MERCHANT_ID"
}

Outgoing Payment request

To create a new outgoing payment request use the POST /payouts/{idPayout} endpoint.

Example CURL for creating new outgoing payment

curl -X POST 'https://api.sandbox.komopay.id/payouts/TST-223344' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'X-API-Version: 2' \
     -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIlBPU1QgL3BheW91dHMvVFNULTIyMzM0NCIsIkdFVCAvcGF5b3V0cy9UU1QtMjIzMzQ0Il0sImV4cCI6MTYyMjYyODQzOCwianRpIjoiZDdiOTI5YTktYTc2Yy00ZWE1LTkwZTUtZmY3YzNkZjE5NTRiIiwiaWF0IjoxNjIyNjI3ODM4LCJzdWIiOiJZT1VSX01FUkNIQU5UX0NPREUifQ.ULgCPXd01mc3JS6QOu6aZUSxw6eDCjpD_IehDkfoQes' \
     -d '{
           "paymentRequested": {
             "money":{
               "amount": 10000,
               "currencyCode": "IDR"
             }
           },
           "paymentMethod": {
             "paymentMethodCode": "BANK_TRANSFER",
             "account":{
               "accountName": "Test account",
               "accountNumber": "11223344"
             },
             "paymentOperatorCode": "BNK_000",
             "emailAddress": "customer@test.com"
           },
           "callbackUrl": "https://callback.example.com"
         }'

Response of the example call

{
  "paymentRequested": {
    "money": {
      "amount": 10000,
      "currencyCode": "IDR"
    }
  },
  "paymentMethodResponse": {
    "paymentMethodCode": "BANK_TRANSFER",
    "idPayout": "TST-223344"
  }
}

Callback

After an outgoing payment is processed notification is sent to the given callback URL. The callback structure is described in the callback section of POST /payouts/{idPayout} endpoint description. For more info about callbacks concepts, see the Callbacks section.

Payment status check

To proactively check outgoing payment status use the GET /payouts/{idPayout} endpoint.

Example CURL for requesting payment detail

curl -X GET 'https://api.sandbox.komopay.id/payouts/TST-223344' \
     -H 'Accept: application/json' \
     -H 'X-API-Version: 2' \
     -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIlBPU1QgL3BheW91dHMvVFNULTIyMzM0NCIsIkdFVCAvcGF5b3V0cy9UU1QtMjIzMzQ0Il0sImV4cCI6MTYyMjYyODQzOCwianRpIjoiZDdiOTI5YTktYTc2Yy00ZWE1LTkwZTUtZmY3YzNkZjE5NTRiIiwiaWF0IjoxNjIyNjI3ODM4LCJzdWIiOiJZT1VSX01FUkNIQU5UX0NPREUifQ.ULgCPXd01mc3JS6QOu6aZUSxw6eDCjpD_IehDkfoQes'

Response of the example call

{
  "paymentRequested": {
    "money": {
      "amount": 42.05,
      "currencyCode": "USD"
    }
  },
  "process": {
    "status": "SUCCESS",
    "createdAt": "2021-05-19T10:57:28.313Z",
    "processedAt": "2021-05-19T10:58:28.313Z",
    "isTest": false
  },
  "fee": {
    "amount": 0.1,
    "currencyCode": "USD"
  },
  "paymentMethodResponse": {
    "paymentMethodCode": "BANK_TRANSFER",
    "idPayout": "TST-112233"
  }
}