Skip to main content

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 TypeDescriptionKey dependency
WALLET_PAYOUTPayments sent to an external beneficiary outside of the Verto network.Requires a pre-created and approved beneficiary.
WALLET_TO_BUSINESSDirect payments made to other businesses onboarded on Verto (V-Pay).Requires the recipient's companyId.
TRANSFER_WITHIN_WALLETSSame-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​

HeaderValueRequiredDescription
AuthorizationBearer {access_token}YesAccess token for authenticated calls.
Content-Typeapplication/jsonYesRequest payload format.
Acceptapplication/jsonYesResponse payload format.
x-api-keystringNoOptional 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​

FieldTypeRequiredDescription
paymentTypestringYesDetermines which payment flow is used.
sourceWalletIdstringYesSource wallet identifier.
sourceAmountnumberYesAmount to transfer from the source wallet.
purposeIdstringConditionalPurpose code or purpose identifier for the payment.
paymentIdstringNoOptional idempotency key generated by client.
customPaymentReferencestringNoFree-text reference stored against the payment.
scheduledDatestringNoScheduled execution date in ISO 8601 format.
recurFrequencystringConditionalRequired when schedule is used.
supportingDocS3Key / supportingDocS3Keysstring / arrayNoSupporting docs references.
verificationOTPstringNoOTP for payment verification.

Typical payment-specific fields​

Payment typeAdditional required fields
WALLET_PAYOUTtargetAccountId, and sender when applicable
WALLET_TO_BUSINESStargetCompanyId
TRANSFER_WITHIN_WALLETStargetWalletId

Response​

Success response: 201 Created​

{
"reference": "TO-29072023-114",
"type": "WALLET_PAYOUT",
"state": "REQUESTED"
}

Response fields​

FieldTypeDescription
referencestringUnique reference for the payment request.
typestringPayment type submitted.
statestringPayment request state, such as REQUESTED, COMPLETED, or CANCELLED.

Error responses​

StatusMeaning
400Invalid input or validation failure.
401Authentication required or invalid.
403Forbidden; insufficient permissions.
500Unexpected 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);
});

Interactive API explorer​