Card Order & Payment Flow
This documentation provides a step-by-step guide to ordering a card through the Vault API. The process involves retrieving cardOfferId
and cardDesignId
, creating a card request, and completing the payment.
Step 1: Obtain cardOfferId
and cardDesignId
cardOfferId
and cardDesignId
Retrieve the unique identifiers for the card offer (cardOfferId
) and available card designs (cardDesignId
) using the List Card Offers endpoint.
Endpoint Details
- Method:
GET
- URL: List Card Offers
Response Example
[
{
"id": "b8488e09-6176-46ee-87cb-b620fcb48f92",
"cardType": "VIRTUAL",
"allowedCardDesigns": [
{
"id": "46534fc8-b74d-4a58-967d-ce6224099940",
"name": "ALLA_GORBUNOVA_SA_USD_DESIGN",
"description": "#B29D7D"
},
{
"id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
"name": "ALLA_GORBUNOVA_SA_USD_REAP",
"description": "#FF00FF"
}
],
"allowUserPrimaryCardname": true,
"allowUserSecondaryCardname": false,
"priceData": [
{
"cardLimit": 1,
"priceAmount": "1",
"priceCurrency": "USDT"
},
{
"cardLimit": 5,
"priceAmount": "2",
"priceCurrency": "USDT"
}
],
"currentPriceAmount": "1",
"currentPriceCurrency": "USDT"
}
]
Field Descriptions
Field | Description |
---|---|
id | cardOfferId: Unique identifier for the card offer. |
cardType | The type of card available (e.g., "VIRTUAL" ). |
allowedCardDesigns | List of available card designs for the card offer. |
allowedCardDesigns.id | cardDesignId: Unique identifier for each available card design. |
allowedCardDesigns.name | The name of the card design (e.g., "ALLA_GORBUNOVA_SA_USD_DESIGN" ). |
allowedCardDesigns.description | A color description for the card design (e.g., "#B29D7D" ). |
allowUserPrimaryCardname | Indicates if users are allowed to choose a primary cardholder name. |
allowUserSecondaryCardname | Indicates if users are allowed to choose a secondary cardholder name. |
priceData | List of available pricing options for the card. |
priceData.cardLimit | The maximum number of cards that can be issued for this price. |
priceData.priceAmount | The price amount for the card, specified in the priceCurrency . |
priceData.priceCurrency | The currency used for the price of the card (e.g., "USDT" ). |
currentPriceAmount | The current price for the card, specified in the currentPriceCurrency . |
currentPriceCurrency | The currency used for the current card price (e.g., "USDT" ). |
Step 2: Create Card Request
After obtaining the cardOfferId
and cardDesignId
, submit a request to create the card.
Endpoint Details
- Method:
POST
- URL: Create Card Request
Request Example
{
"cardOfferId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"accountId": "string",
"preferredCardname": "string",
"secondaryCardname": "string",
"billingAddress": {
"firstName": "string",
"lastName": "string",
"email": "[email protected]",
"phone": "string",
"country": "GBR",
"postCode": "SW1A 1AA",
"state": "MA",
"town": "London",
"street": "Downing Street",
"subStreet": "10",
"buildingName": "Buckingham Palace",
"flatNumber": "1",
"buildingNumber": "10"
},
"cardDesignId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
'
Response Example
[
{
"id": "f30686ad-e009-4595-808a-a86eaf227b2f",
"status": "INIT",
"createdDate": "2024-11-07T12:15:04.947757Z",
"cardName": "John Mock-Doe",
"secondaryCardName": "false",
"cardType": "VIRTUAL",
"cardDesign": {
"id": "46534fc8-b74d-4a58-967d-ce6224099940",
"name": "ALLA_GORBUNOVA_SA_USD_DESIGN",
"description": "#B29D7D"
},
"invoiceId": "a3562d2e-3318-4faa-8498-f94aa834cc84"
}
]
Response Field Descriptions
Field | Description |
---|---|
id | cardId: Unique identifier for the card. |
status | The current status of the card request (e.g., "INIT" ). |
createdDate | The date and time when the card was created in ISO 8601 format. |
cardName | The name on the card (e.g., "John Mock-Doe" ). |
secondaryCardName | Indicates whether a secondary cardholder name is provided (true /false ). |
cardType | The type of the card (e.g., "VIRTUAL" ). |
cardDesign | The design selected for the card. |
cardDesign.id | cardDesignId: Unique identifier for the card design. |
cardDesign.name | The name of the selected card design (e.g., "ALLA_GORBUNOVA_SA_USD_DESIGN" ). |
cardDesign.description | A color description for the card design (e.g., "#B29D7D" ). |
invoiceId | invoiceId: Unique identifier for the associated invoice. |
Step 3: Create Invoice Payment
After successfully creating the card request and obtaining the unique invoiceId
, proceed to initiate payment for the invoice.
Endpoint Details
- Method:
POST
- URL: Create Invoice Payment
Request Parameters
Parameter | Type | Description |
---|---|---|
paymentId | string | The unique identifier for the payment. |
invoiceId | string | The internal invoice ID associated with the payment. |
type | string | The type of payment provider (e.g., PLATFORM , CHECKOUT ). |
accountId | string | The internal account ID associated with the user making the payment. |
currency | string | The currency used for the payment. |
anyCurrency | boolean | Indicates if multiple currencies can be prioritized (true or false ). |
Request Example
{
"paymentId": "f91c7e6d-5b8f-4727-a4dc-52b1b5c053df",
"invoiceId": "a3562d2e-3318-4faa-8498-f94aa834cc84",
"type": "PLATFORM",
"accountId": "123456",
"currency": "USDT",
"anyCurrency": true
}
Response Example
{
"id": "d71686ac-e010-4596-908b-a87eaf128a3f", // Payment ID
"invoiceId": "a3562d2e-3318-4faa-8498-f94aa834cc84", // Invoice ID
"status": "PROCESSING", // Payment status (e.g., INIT, PROCESSING, SUCCESS, FAILED)
"type": "PLATFORM", // Payment method type
"accountId": "123456" // Internal account used for payment
}
Step 4: Confirm Invoice Payment
This step finalizes the payment process for a previously initiated invoice payment.
Endpoint Details
- Method:
POST
- URL: Confirm Invoice Payment
Request Parameters
Parameter | Type | Description |
---|---|---|
paymentId | string | Unique identifier for the payment to be confirmed. |
invoiceId | string | Unique identifier for the associated invoice. |
type | string | Type of payment provider (e.g., PLATFORM , CHECKOUT ). |
accountId | string | Internal account ID of the user making the payment. |
currency | string | Currency used for the payment (e.g., USD , EUR ). |
anyCurrency | boolean | Whether the payment supports multiple currencies (true or false ). |
Request Example
{
"paymentId": "d71686ac-e010-4596-908b-a87eaf128a3f",
"invoiceId": "a3562d2e-3318-4faa-8498-f94aa834cc84",
"type": "PLATFORM",
"accountId": "123456",
"currency": "USDT",
"anyCurrency": true
}
Response Example
{
"id": "d71686ac-e010-4596-908b-a87eaf128a3f", // Payment ID
"invoiceId": "a3562d2e-3318-4faa-8498-f94aa834cc84", // Invoice ID
"status": "SUCCESS", // Payment status (e.g., INIT, PROCESSING, SUCCESS, FAILED)
"type": "PLATFORM", // Payment method type
"accountId": "123456" // Internal account ID associated with the payment
}
Updated 23 days ago