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

Submitting сustomer information
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": "John",
    "lastName": "Doe",
    "middleName": "James",
    "phone": "79221110500",
    "email": "john.doe@mymail.com"
  },
  "recipient": {
    "walletData": {
      "walletId": "eWallet12345",
      "walletHolderName": "John Smith"
    }
  }
}'

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
connectpay

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'

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
connectpay

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

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

Step 3: Create payout

Request

ofapay
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": "test01"
  },
  "purpose": "payment for test",
  "providerCode": "ofapay",
  "acquirerCode": "paymaya",
  "instrumentType": "wallet",
  "dataEntryMode": "h2h",
  "recipient": {
    "walletData": {
      "walletId": "eWallet12345",
      "walletHolderName": "John Smith"
    }
  }
}'

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
connectpay

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

{
  "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
premierpay

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'

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
premierpay

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

{
  "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
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": "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"
    }
  }
}'

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
premierpay

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

{
  "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"
  }
}

Overview​

Retrieve available payout methods for a shop​

Creating a Payout with Customer Information / Updating Existing Customer Information​

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

For wallet payouts​

Step 1: Retrieve payout methods​

Step 2: Retrieve required payout fields​

Step 3: Create payout​

Step 4: Check payout status​

For bank transfer payouts​

Step 1: Retrieve payout methods​

Step 2: Retrieve required payout fields​

Step 3: Create payout​

Step 4: Check payout status​

For card payouts​

Step 1: Retrieve payout methods​

Step 2: Retrieve required payout fields​

Step 3: Create payout​

Step 4: Check payout status​

Overview

Retrieve available payout methods for a shop

Creating a Payout with Customer Information / Updating Existing Customer Information

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

For wallet payouts

Step 1: Retrieve payout methods

Step 2: Retrieve required payout fields

Step 3: Create payout

Step 4: Check payout status

For bank transfer payouts

Step 1: Retrieve payout methods

Step 2: Retrieve required payout fields

Step 3: Create payout

Step 4: Check payout status

For card payouts

Step 1: Retrieve payout methods

Step 2: Retrieve required payout fields

Step 3: Create payout

Step 4: Check payout status