Create a payment request
Overview
Creates a new payment request based on the specified payment type. Supports wallet-to-business transfers, wallet payouts to bank accounts, and transfers within wallets. The payment type determines the required fields and validation rules applied.
Payment type overview
Before initiating a transaction, make sure you select the appropriate payment type for your integration needs.
| Payment Type | Description | Key dependency |
|---|---|---|
WALLET_PAYOUT | Payments sent to an external beneficiary outside of the Verto network. | Requires a pre-created and approved beneficiary. |
WALLET_TO_BUSINESS | Direct payments made to other businesses onboarded on Verto (V-Pay). | Requires the recipient's companyId. |
TRANSFER_WITHIN_WALLETS | Same-currency transfers between wallets owned by your organization. | Requires destination walletID. |
Sender information
The sender object is required for WALLET_PAYOUT payments when you are a fintech or financial institution making a payout on behalf of an underlying customer from your master wallet. This applies to both corporate and individual senders. It is not required for WALLET_TO_BUSINESS or TRANSFER_WITHIN_WALLETS payment types.
This is not required if you are:
- An Atlas for Platform client — sender identity is established through the sub-account's KYB data
- A corporate entity sending on your own principal basis
- Initiating a payout from a sub-account — sender information is inherited from the sub-account directly
If you are unsure whether your use case requires a sender object, contact the Verto API support team before going live.
Resource access
- HTTP method:
POST - Endpoint:
/banking/ibans/v2/payments/create - Authentication: required when applicable to your environment
Request headers
| Header | Value | Required | Description |
|---|---|---|---|
Authorization | Bearer {access_token} | Yes | Access token for authenticated calls. |
Content-Type | application/json | Yes | Request payload format. |
Accept | application/json | Yes | Response payload format. |
x-api-key | string | No | Optional API key for environment access. |
Request body
The request body is polymorphic. The paymentType field decides which schema is used and which required fields are enforced.
Example: wallet payout
{
"paymentType": "WALLET_PAYOUT",
"sourceWalletId": "12345",
"sourceAmount": 1000.5,
"targetAccountId": "67890",
"purposeId": "1",
"customPaymentReference": "Invoice payment #12345"
}
Example: wallet-to-business transfer
{
"paymentType": "WALLET_TO_BUSINESS",
"sourceWalletId": "12345",
"sourceAmount": 500,
"targetCompanyId": "98765",
"purposeId": "2"
}
Example: transfer within wallets
{
"paymentType": "TRANSFER_WITHIN_WALLETS",
"sourceWalletId": "12345",
"sourceAmount": 250,
"targetWalletId": "67890"
}
Common request fields
| Field | Type | Required | Description |
|---|---|---|---|
paymentType | string | Yes | Determines which payment flow is used. |
sourceWalletId | string | Yes | Source wallet identifier. |
sourceAmount | number | Yes | Amount to transfer from the source wallet. |
purposeId | string | Conditional | Purpose code or purpose identifier for the payment. |
paymentId | string | No | Optional idempotency key generated by client. |
customPaymentReference | string | No | Free-text reference stored against the payment. |
scheduledDate | string | No | Scheduled execution date in ISO 8601 format. |
recurFrequency | string | Conditional | Required when schedule is used. |
supportingDocS3Key / supportingDocS3Keys | string / array | No | Supporting docs references. |
verificationOTP | string | No | OTP for payment verification. |
Typical payment-specific fields
| Payment type | Additional required fields |
|---|---|
WALLET_PAYOUT | targetAccountId, and sender when applicable |
WALLET_TO_BUSINESS | targetCompanyId |
TRANSFER_WITHIN_WALLETS | targetWalletId |
Response
Success response: 201 Created
{
"reference": "TO-29072023-114",
"type": "WALLET_PAYOUT",
"state": "REQUESTED"
}
Response fields
| Field | Type | Description |
|---|---|---|
reference | string | Unique reference for the payment request. |
type | string | Payment type submitted. |
state | string | Payment request state, such as REQUESTED, COMPLETED, or CANCELLED. |
Error responses
| Status | Meaning |
|---|---|
400 | Invalid input or validation failure. |
401 | Authentication required or invalid. |
403 | Forbidden; insufficient permissions. |
500 | Unexpected server-side error. |
Code examples
cURL
curl -X POST \
'https://api-payment-sandbox.vertofx.com/payments/create' \
-H 'Content-Type: application/json' \
-d '{
"paymentType": "TRANSFER_WITHIN_WALLETS",
"sourceWalletId": "12345",
"sourceAmount": 250,
"targetWalletId": "67890"
}'
Python
import requests
url = 'https://api-payment-sandbox.vertofx.com/payments/create'
headers = {
'Content-Type': 'application/json'
}
payload = {
'paymentType': 'WALLET_TO_BUSINESS',
'sourceWalletId': '12345',
'sourceAmount': 500,
'targetCompanyId': '98765',
'purposeId': '2'
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())
JavaScript (Node.js)
const axios = require('axios');
const url = 'https://api-payment-sandbox.vertofx.com/payments/create';
const payload = {
paymentType: 'WALLET_PAYOUT',
sourceWalletId: '12345',
sourceAmount: 1000.5,
targetAccountId: '67890',
purposeId: '1',
customPaymentReference: 'Invoice payment #12345'
};
axios.post(url, payload)
.then((response) => {
console.log(response.status, response.data);
})
.catch((error) => {
console.error(error.response ? error.response.data : error.message);
});