API: Request examples

Overview

This documentation provides an overview of the Payouts API endpoints, including requests and responses for creating payouts, retrieving payout methods, and checking payout statuses.

The examples use shop ID 115 and the test environment (stage).

Retrieve available payout methods for a shop

Request

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/payout-methods/115' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": [
    {
      "providerCode": "connectpay",
      "acquirerCode": "gcash",
      "instrumentType": "wallet",
      "entryMode": null,
      "dataEntryModes": [
        "h2h"
      ],
      "allowedCards": [],
      "transferType": null,
      "currencies": [
        "PHP"
      ],
      "regions": [
        "PH"
      ],
      "isDefault": false
    },
    {
      "providerCode": "monetix",
      "acquirerCode": "monetix",
      "instrumentType": "bank_transfer",
      "entryMode": null,
      "dataEntryModes": [
        "h2h"
      ],
      "allowedCards": [],
      "transferType": "bank_wire",
      "currencies": [
        "MYR"
      ],
      "regions": [
        "MY"
      ],
      "isDefault": false
    },
    {
      "providerCode": "premierpay",
      "acquirerCode": "directcredit",
      "instrumentType": "bank_transfer",
      "entryMode": null,
      "dataEntryModes": [
        "h2h"
      ],
      "allowedCards": [],
      "transferType": "bank_wire",
      "currencies": [
        "CAD"
      ],
      "regions": [
        "CA"
      ],
      "isDefault": false
    },
    {
      "providerCode": "ofapay",
      "acquirerCode": "paymaya",
      "instrumentType": "wallet",
      "entryMode": null,
      "dataEntryModes": [
        "h2h"
      ],
      "allowedCards": [],
      "transferType": null,
      "currencies": [
        "PHP"
      ],
      "regions": [
        "PH"
      ],
      "isDefault": false
    }
  ]
}

Creating a Payout with Customer Information / Updating Existing Customer Information

If you need to update the customer information with the corresponding customerId, simply pass the same customerId, specify the required fields for the customer object (First Name, Last Name), and provide the updated customer information.

Request

Request

Submitting сustomer information

curl -L -X POST 'https://gateway.stage.vertexgateway.com/api/v1/payouts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "payout": {
    "cost": {
      "amount": "100.50",
      "currency": "PHP"
    },
    "payoutNumber": "test001"
  },
  "purpose": "payment for test",
  "providerCode": "ofapay",
  "acquirerCode": "paymaya",
  "instrumentType": "wallet",
  "dataEntryMode": "h2h",
  "customer": {
    "customerId": "1",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "James",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  },
  "recipient": {
    "walletData": {
      "walletId": "eWallet12345",
      "walletHolderName": "John Smith"
    }
  }
}'

Updating customer information

curl -L -X POST 'https://gateway.stage.vertexgateway.com/api/v1/payouts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "payout": {
    "cost": {
      "amount": "100.50",
      "currency": "PHP"
    },
    "payoutNumber": "test001"
  },
  "purpose": "payment for test",
  "providerCode": "ofapay",
  "acquirerCode": "paymaya",
  "instrumentType": "wallet",
  "dataEntryMode": "h2h",
  "customer": {
    "customerId": "1",
    "firstName": "Jane",
    "lastName": "Smith",
    "middleName": "James",
    "phone": "15857345783",
    "email": "janesmith@example.com"
  },
  "recipient": {
    "walletData": {
      "walletId": "eWallet12345",
      "walletHolderName": "John Smith"
    }
  }
}'

Complete Flow: Retrieve payout methods, create payout, check status

For wallet payouts

Step 1: Retrieve payout methods

Request

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/payout-methods/115' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": [
    {
      "providerCode": "ofapay",
      "acquirerCode": "paymaya",
      "instrumentType": "wallet",
      "entryMode": null,
      "dataEntryModes": [
        "h2h"
      ],
      "allowedCards": [],
      "transferType": null,
      "currencies": [
        "PHP"
      ],
      "regions": [
        "PH"
      ],
      "isDefault": false
    },
    {
      "providerCode": "connectpay",
      "acquirerCode": "gcash",
      "instrumentType": "wallet",
      "entryMode": null,
      "dataEntryModes": [
        "h2h"
      ],
      "allowedCards": [],
      "transferType": null,
      "currencies": [
        "PHP"
      ],
      "regions": [
        "PH"
      ],
      "isDefault": false
    }
  ]
}

Step 2: Retrieve required payout fields

Request

ofapay

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/fields/ofapay/wallet/' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

connectpay

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/fields/connectpay/wallet/' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

ofapay

{
  "data": {
    "recipient": {
      "walletData": [
        "walletId",
        "walletHolderName"
      ]
    },
    "payoutOptions": {
      "supportedRecipientBanks": []
    }
  }
}

connectpay

{
  "data": {
    "recipient": {
      "personalData": [
        "phone"
      ]
    },
    "payoutOptions": {
      "supportedRecipientBanks": []
    }
  }
}

Step 3: Create payout

Request

ofapay

curl -L -X POST 'https://gateway.stage.vertexgateway.com/api/v1/payouts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "payout": {
    "cost": {
      "amount": "100.50",
      "currency": "PHP"
    },
    "payoutNumber": "test01"
  },
  "purpose": "payment for test",
  "providerCode": "ofapay",
  "acquirerCode": "paymaya",
  "instrumentType": "wallet",
  "dataEntryMode": "h2h",
  "recipient": {
    "walletData": {
      "walletId": "eWallet12345",
      "walletHolderName": "John Smith"
    }
  }
}'

connectpay

curl -L -X POST 'https://gateway.stage.vertexgateway.com/api/v1/payouts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "payout": {
    "cost": {
      "amount": "100.50",
      "currency": "PHP"
    },
    "payoutNumber": "test02"
  },
  "purpose": "test payout",
  "providerCode": "connectpay",
  "acquirerCode": "gcash",
  "instrumentType": "wallet",
  "dataEntryMode": "h2h",
  "recipient": {
    "personalData": {
      "phone": "+15557654321"
    }
  }
}'

Response

ofapay

{
  "data": {
    "payoutStatus": "in_progress",
    "payoutNumber": "test01"
  }
}

connectpay

{
  "data": {
    "payoutStatus": "in_progress",
    "payoutNumber": "test02"
  }
}

Step 4: Check payout status

Request

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/115/test01' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": {
    "payoutStatus": "in_progress",
    "payoutNumber": "test02"
  }
}

For bank transfer payouts

Step 1: Retrieve payout methods

Request

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/payout-methods/115' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": [
    {
      "providerCode": "monetix",
      "acquirerCode": "monetix",
      "instrumentType": "bank_transfer",
      "entryMode": null,
      "dataEntryModes": [
        "h2h"
      ],
      "allowedCards": [],
      "transferType": "bank_wire",
      "currencies": [
        "MYR"
      ],
      "regions": [
        "MY"
      ],
      "isDefault": false
    },
    {
      "providerCode": "premierpay",
      "acquirerCode": "directcredit",
      "instrumentType": "bank_transfer",
      "entryMode": null,
      "dataEntryModes": [
        "h2h"
      ],
      "allowedCards": [],
      "transferType": "bank_wire",
      "currencies": [
        "CAD"
      ],
      "regions": [
        "CA"
      ],
      "isDefault": false
    }
  ]
}

Step 2: Retrieve required payout fields

Request

monetix

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/fields/monetix/bank_transfer/' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

premierpay

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/fields/premierpay/bank_transfer/' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

monetix

{
  "data": {
    "recipient": {
      "personalData": [
        "email",
        "firstName",
        "lastName"
      ],
      "bankTransferData": [
        "accountNumber"
      ]
    },
    "payoutOptions": {
      "supportedRecipientBanks": []
    }
  }
}

premierpay

{
  "data": {
    "recipient": {
      "": [
        ""
      ],
      "bankTransferData": [
        "transitNumber",
        "accountNumber",
        "accountName"
      ],
      "personalData": [
        "firstName",
        "lastName",
        "email",
        "phone"
      ],
      "addressData": [
        "address",
        "city",
        "state",
        "countryCode",
        "zipCode"
      ]
    },
    "payoutOptions": {
      "supportedRecipientBanks": []
    }
  }
}

Step 3: Create payout

Request

monetix

curl -L -X POST 'https://gateway.stage.vertexgateway.com/api/v1/payouts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "payout": {
    "cost": {
      "amount": "100.50",
      "currency": "MYR"
    },
    "payoutNumber": "test03"
  },
  "purpose": "for test payment",
  "providerCode": "monetix",
  "acquirerCode": "monetix",
  "instrumentType": "bank_transfer",
  "transferType": "bank_wire",
  "dataEntryMode": "h2h",
  "recipient": {
    "personalData": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com"
    },
    "bankTransferData": {
      "accountNumber": "123456789012"
    }
  }
}'

premierpay

curl -L -X POST 'https://gateway.stage.vertexgateway.com/api/v1/payouts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "payout": {
    "cost": {
      "amount": "100.50",
      "currency": "CAD"
    },
    "payoutNumber": "test04"
  },
  "purpose": "for test purpose",
  "providerCode": "premierpay",
  "acquirerCode": "directcredit",
  "instrumentType": "bank_transfer",
  "transferType": "bank_wire",
  "dataEntryMode": "h2h",
  "recipient": {
    "personalData": {
      "firstName": "John",
      "lastName": "Smith",
      "phone": "+15557654321",
      "email": "john.smith@example.com"
    },
    "addressData": {
      "countryCode": "US",
      "state": "NY",
      "city": "New York",
      "zipCode": "10001",
      "address": "456 Liberty Ave."
    },
    "documentData": {
      "identityDocumentId": "AB1234567",
      "TIN": "123456789012"
    },
    "bankTransferData": {
      "accountNumber": "123456789012",
      "accountName": "John A. Doe",
      "transitNumber": "001"
    }
  }
}'

Response

monetix

{
  "data": {
    "payoutStatus": "in_progress",
    "payoutNumber": "test03"
  }
}

premierpay

{
  "data": {
    "payoutStatus": "in_progress",
    "payoutNumber": "test04"
  }
}

Step 4: Check payout status

Request

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/115/test03' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": {
    "payoutStatus": "in_progress",
    "payoutNumber": "test03"
  }
}

For card payouts

Step 1: Retrieve payout methods

Request

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/payout-methods/115' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": [
    {
      "providerCode": "paysage",
      "acquirerCode": "paysage",
      "instrumentType": "card",
      "entryMode": "cnp",
      "dataEntryModes": [
        "h2h"
      ],
      "allowedCards": [
        "visa",
        "mastercard"
      ],
      "transferType": null,
      "currencies": [
        "EUR"
      ],
      "regions": [
        "AX",
        "DZ"
      ],
      "isDefault": false
    }
  ]
}

Step 2: Retrieve required payout fields

Request

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/fields/paysage/card/' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": {
    "recipient": {
      "personalData": [
        "email",
        "firstName",
        "lastName"
      ],
      "cardData": [
        "cardNumber"
      ]
    },
    "payoutOptions": {
      "supportedRecipientBanks": []
    }
  }
}

Step 3: Create payout

Request

curl -L -X POST 'https://gateway.stage.vertexgateway.com/api/v1/payouts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999' \
--data-raw '{
  "shopId": 115,
  "payout": {
    "cost": {
      "amount": "100.50",
      "currency": "EUR"
    },
    "payoutNumber": "test_payout3"
  },
  "purpose": "some text",
  "providerCode": "paysage",
  "acquirerCode": "paysage",
  "instrumentType": "card",
  "dataEntryMode": "h2h",
  "customer": {
    "customerId": "56656",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "James",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  },
  "recipient": {
    "personalData": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com"
    },
    "cardData": {
      "cardNumber": "4111111111111111"
    }
  }
}'

Response

{
  "data": {
    "payoutStatus": "in_progress",
    "payoutNumber": "test_payout3"
  }
}

Step 4: Check payout status

Request

curl -L -X GET 'https://gateway.stage.vertexgateway.com/api/v1/payouts/115/test_payout3' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: 2d10f5be-e7fa-463e-b79e-6cb7cd226999'

Response

{
  "data": {
    "payoutStatus": "in_progress",
    "payoutNumber": "test_payout3"
  }
}