This documentation provides a step-by-step guide to ordering a physical or virtual card through the Vault API. The process involves retrieving cardOfferId and cardDesignId, creating a card request, providing necessary details, and completing the payment.

Step 1: Retrieve Available Card Offers

Retrieve the available card offers.

Endpoint:

GET /v1/card-offers

Response Example

  {
        "id": "7b60a26c-762a-4af8-ab31-006d2fb197a1",
        "cardType": "PHYSICAL",
        "allowedCardDesigns": [
            {
                "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
                "name": "ALLA_GORBUNOVA_SA_USD_REAP",
                "color": {
                    "name": "ORANGE",
                    "hexValue": "#FC6434"
                }
            },
            {
                "id": "46534fc8-b74d-4a58-967d-ce6224099940",
                "name": "ALLA_GORBUNOVA_SA_USD_DESIGN",
                "color": {
                    "name": "GOLD",
                    "hexValue": "#B29D7D"
                }
            }

Step 2: Create a Card Request

After selecting a cardOfferId and cardDesignId, submit a request to create a card.

Endpoint:

POST /v1/card-requests

Request Parameters

Parameter	Type	Required	Description
`cardOfferId`	string	✅	The unique identifier for the card offer.
`cardDesignId`	string	✅	The unique identifier for the selected card design.

Request Example

{
  "cardOfferId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "cardDesignId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Response Example

{
    "id": "e1907e2c-cefc-49b2-8d43-168a78e5da93",
    "cardType": "PHYSICAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [],
    "cardDesign": {
        "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
        "name": "ALLA_GORBUNOVA_SA_USD_REAP",
        "color": {
            "name": "ORANGE",
            "hexValue": "#FC6434"
        }
    }
}

Possible values for the `STATUS` field

Status	Description
`DATA_COLLECTION`	The card issuance request has been initiated; the user should now provide all necessary information.
`PENDING`	Request pending review.
`INVOICE_FAILED`	The invoice payment has failed and can not be processed. User should verify payment details and submit again.
`FAILED`	The card issuance request has been blocked by the issuing provider. User should contact support for resolution.

Possible values for the `additionalStatuses` field

Reflect the progress of collecting details for the card issuance request. For example, if only CARDHOLDER_NAME is retrieved, it means the user still needs to submit address and payment information.

Status	Description
`CARDHOLDER_NAME`	Name of the cardholder associated with this request.
`BILLING_ADDRESS`	Billing address linked to the card request.
`DELIVERY_ADDRESS`	Delivery address request data for a card.
`INVOICE_PAID`	The ID of the paid invoice associated with this request.

📘
For virtual cards, the payment invoice ID is generated right after request creation.
For physical cards, it becomes available only after the delivery address is provided.

A card issuance request can be cancelled via DELETE card-holder/v1/card-requests/{cardRequestId} endpoint with any status except PENDING.

Step 3: Set Cardholder's Name

Provide the cardholder's name.

Endpoint:

POST /v1/card-requests/{cardRequestId}/cardholder-name

Path Parameters

Parameter	Type	Required	Description
`cardRequestId`	string	✅	The unique identifier of the card request.

Body Parameters

Parameter	Type	Required	Description
`cardholderName`	string	✅	Name of the cardholder to be set on the card.

Request Example

{
  "cardholderName": "John Doe"
}

Response Example

{
    "id": "62ef4eec-0eaf-44ad-ac43-41b535232634",
    "cardType": "PHYSICAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [
        "CARDHOLDER_NAME"
    ],
    "cardholderName": "John Mock-Doe",
    "cardDesign": {
        "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
        "name": "ALLA_GORBUNOVA_SA_USD_REAP",
        "color": {
            "name": "ORANGE",
            "hexValue": "#FC6434"
        }
    }
}

📘
Key Notes
If the requested card type is PHYSICAL, the cardholder name provided in the cardRequestId path parameter will be printed on the card.
Cardholder Name Requirements (Physical Cards):

allowed characters: Latin letters, numbers, spaces, and hyphens;

length limits: total — up to 27 characters, individual names — up to 13 characters each (first & last name);

Format: first and last names must be separated by a round closing bracket ) (e.g.,John)Doe).

This endpoint can also update a cardholder’s name.

Step 4: Set Address

Submit the billing and delivery address details.

Endpoint:

POST /v1/card-requests/{cardRequestId}/address

Path Parameters

Parameter	Type	Required	Description
`cardRequestId`	string	✅	The unique identifier of the card request.

Body Parameters

Parameter	Type	Required	Description
`billing`	string	✅	Billing address request data for a card.
`delivery`	string	✅	Delivery address request data for a card — required if the requested card type is`PHYSICAL`

Request Example

{
  "billing": {
    "country": "string",
    "state": "string",
    "city": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "postalCode": "string"
  },
  "delivery": {
    "country": "string",
    "state": "string",
    "city": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "postalCode": "string",
    "firstName": "string",
    "lastName": "string",
    "phone": "string",
    "dialCode": "string"
  }
}

Response Example

{
    "id": "62ef4eec-0eaf-44ad-ac43-41b535232634",
    "cardType": "PHYSICAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [
        "CARDHOLDER_NAME",
        "BILLING_ADDRESS",
        "DELIVERY_ADDRESS"
    ],
    "invoiceId": "990a4039-4384-4ab8-b239-56dc6fc86632",
    "cardholderName": "John Mock-Doe",
    "billingAddress": {
        "country": "AUT",
        "state": "Vien",
        "city": "Vien",
        "addressLine1": "Schweine",
        "addressLine2": "2",
        "postalCode": "115462"
    },
    "deliveryAddress": {
        "country": "AUT",
        "state": "Vien",
        "city": "Vien",
        "addressLine1": "Bukhen Wisebier",
        "addressLine2": "62",
        "postalCode": "51552555",
        "firstName": "John",
        "lastName": "Mock Doe",
        "phone": 4366565973028,
        "dialCode": 43
    },
    "cardDesign": {
        "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
        "name": "ALLA_GORBUNOVA_SA_USD_REAP",
        "color": {
            "name": "ORANGE",
            "hexValue": "#FC6434"
        }
    }
}

You can use the invoiceId parameter with the Get Invoice by ID endpoint to retrieve all details for a specific invoice.

Supported countries for plastic card delivery and associated shipping prices can be retrieved by using Get Delivery Countries List endpoint.

Optional. Apply Discount to Invoice

Endpoint:

PUT /acquiring/invoice/{invoiceId}/discount

Enables clients to apply promotional discounts before finalizing the payment.

Path Parameters:

Name	Type	Required	Description
`invoiceId`	`string`	✅	the invoice ID.

Query Parameters:

Name	Type	Required	Description
`discountCode`	`string`	✅	the discount code to be applied to the invoice, which may provide a percentage or fixed discount.

Response Example:

{
  "status" : "INIT",
  "payments" : [ ],
  "discountCode" : "WELCOME100",
  "amountBeforeDiscount" : 102,
  "lastModifiedDate" : "2025-04-22T10:22:47.441401859Z",
  "recurrentInvoiceId" : "034cd818-18ca-4896-bfe2-cc7c445320cb",
  "externalClientId" : "8a7b9019-bec5-4580-9b34-31a0b8fb613f",
  "id" : "fea628c5-fa29-4f54-98ef-e4a2ede4d755",
  "amount" : 0.00000000,
  "currency" : "usd",
  "type" : "ORIGINAL",
  "alignable" : true
}

Once you use this endpoint, response body retrieved by Get Invoice by ID endpoint will be changed — as the discountCode and AmountBeforeDiscount parameters will be updated.

Step 5. Initialize Payment

Endpoint:

POST /invoice/payment

Initializes the payment for the card.

Body Parameters:

Name	Type	Required	Description
`invoiceId`	`string`	✅	the invoice ID.
`type`	`string`	✅	Payment provider type (only `PLATFORM` one is available).
`accountId`	`string`	✅	Identifies the `CHECKING` type of account in the wallet service. All accounts can be retrieved using List all accounts endpoint.
`currency`	`string`	✅	Currency used for the payment.
`anyCurrency`	`boolean`	✅	Flag indicating whether multiple currencies are supported.

Response Example:

{
  "accountId" : "59341629-5f86-47a5-a867-1c4225f119b0",
  "id" : "8caf4504-d6b0-461b-9b67-53dacee85156",
  "invoiceId" : "a90f36dd-57af-4f5e-a2f5-086631f9edac",
  "status" : "INIT",
  "type" : "PLATFORM",
  "amount" : 15,
  "description" : "Invoice payment",
  "last_modified_date" : "2025-04-07T21:32:11.716207540Z",
  "created_date" : "2025-04-07T21:32:11.716207540Z"
}

Step 6. Confirm Invoice Payment

Endpoint:

POST /payment/pay

Confirms the payment of the invoice.

Body Parameters:

Name	Type	Required	Description
`invoiceId`	`string`	✅	the invoice ID.
`type`	`string`	✅	Payment provider type (only `PLATFORM` one is available).
`paymentId`	`string`	✅	Unique identifier for the payment from Step 4.
`accountId`	`string`	✅	Identifies the `CHECKING` type of account in the wallet service. All accounts can be retrieved using List all accounts endpoint.
`currency`	`string`	✅	Currency used for the payment.
`anyCurrency`	`boolean`	✅	Flag indicating whether multiple currencies are supported.

Response Example:

{
  "accountId" : "59341629-5f86-47a5-a867-1c4225f119b0",
  "id" : "8caf4504-d6b0-461b-9b67-53dacee85156",
  "invoiceId" : "a90f36dd-57af-4f5e-a2f5-086631f9edac",
  "status" : "PROCESSING",
  "type" : "PLATFORM",
  "amount" : 15,
  "description" : "Invoice payment",
  "last_modified_date" : "2025-04-07T21:32:14.700515749Z",
  "created_date" : "2025-04-07T21:32:11.716208Z"
}

Once card issuance is approved, the request no longer appears in the Get Card Requests response, but the issued card becomes available via the List All Cards endpoint.

Card Order & Payment Flow

Step 1: Retrieve Available Card Offers

Endpoint:

Response Example

Step 2: Create a Card Request

Endpoint:

Request Parameters

Request Example

Response Example

Possible values for the `STATUS` field

Possible values for the `additionalStatuses` field

📘

Step 3: Set Cardholder's Name

Endpoint:

Path Parameters

Body Parameters

Request Example

Response Example

📘
Key Notes

Step 4: Set Address

Endpoint:

Path Parameters

Body Parameters

Request Example

Response Example

Optional. Apply Discount to Invoice

Endpoint:

Path Parameters:

Query Parameters:

Response Example:

Step 5. Initialize Payment

Endpoint:

Body Parameters:

Response Example:

Step 6. Confirm Invoice Payment

Endpoint:

Body Parameters:

Response Example:

Step 1: Retrieve Available Card Offers

Endpoint:

Response Example

Step 2: Create a Card Request

Endpoint:

Request Parameters

Request Example

Response Example

Possible values for the STATUS field

Possible values for the additionalStatuses field

📘

Step 3: Set Cardholder's Name

Endpoint:

Path Parameters

Body Parameters

Request Example

Response Example

📘Key Notes

Step 4: Set Address

Endpoint:

Path Parameters

Body Parameters

Request Example

Response Example

Optional. Apply Discount to Invoice

Endpoint:

Path Parameters:

Query Parameters:

Response Example:

Step 5. Initialize Payment

Endpoint:

Body Parameters:

Response Example:

Step 6. Confirm Invoice Payment

Endpoint:

Body Parameters:

Response Example:

Possible values for the `STATUS` field

Possible values for the `additionalStatuses` field

📘
Key Notes