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

Retrieve the unique identifiers for the card offer (cardOfferId) and available card designs (cardDesignId) using the List Card Offers endpoint.

Endpoint Details

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

FieldDescription
idcardOfferId: Unique identifier for the card offer.
cardTypeThe type of card available (e.g., "VIRTUAL").
allowedCardDesignsList of available card designs for the card offer.
allowedCardDesigns.idcardDesignId: Unique identifier for each available card design.
allowedCardDesigns.nameThe name of the card design (e.g., "ALLA_GORBUNOVA_SA_USD_DESIGN").
allowedCardDesigns.descriptionA color description for the card design (e.g., "#B29D7D").
allowUserPrimaryCardnameIndicates if users are allowed to choose a primary cardholder name.
allowUserSecondaryCardnameIndicates if users are allowed to choose a secondary cardholder name.
priceDataList of available pricing options for the card.
priceData.cardLimitThe maximum number of cards that can be issued for this price.
priceData.priceAmountThe price amount for the card, specified in the priceCurrency.
priceData.priceCurrencyThe currency used for the price of the card (e.g., "USDT").
currentPriceAmountThe current price for the card, specified in the currentPriceCurrency.
currentPriceCurrencyThe 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

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

FieldDescription
idcardId: Unique identifier for the card.
statusThe current status of the card request (e.g., "INIT").
createdDateThe date and time when the card was created in ISO 8601 format.
cardNameThe name on the card (e.g., "John Mock-Doe").
secondaryCardNameIndicates whether a secondary cardholder name is provided (true/false).
cardTypeThe type of the card (e.g., "VIRTUAL").
cardDesignThe design selected for the card.
cardDesign.idcardDesignId: Unique identifier for the card design.
cardDesign.nameThe name of the selected card design (e.g., "ALLA_GORBUNOVA_SA_USD_DESIGN").
cardDesign.descriptionA color description for the card design (e.g., "#B29D7D").
invoiceIdinvoiceId: 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

Request Parameters

ParameterTypeDescription
paymentIdstringThe unique identifier for the payment.
invoiceIdstringThe internal invoice ID associated with the payment.
typestringThe type of payment provider (e.g., PLATFORM, CHECKOUT).
accountIdstringThe internal account ID associated with the user making the payment.
currencystringThe currency used for the payment.
anyCurrencybooleanIndicates 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

Request Parameters

ParameterTypeDescription
paymentIdstringUnique identifier for the payment to be confirmed.
invoiceIdstringUnique identifier for the associated invoice.
typestringType of payment provider (e.g., PLATFORM, CHECKOUT).
accountIdstringInternal account ID of the user making the payment.
currencystringCurrency used for the payment (e.g., USD, EUR).
anyCurrencybooleanWhether 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
}