Guides
Start typing to search…

Card Order & Payment Flow

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. This guide covers the card ordering process for both Card Program 1 (CP1) and Card Program 2 (CP2) providers.

Provider Differences

FeatureCard Program 1 (CP1)Card Program 2 (CP2)
Card TypesVirtual & PhysicalVirtual only
KYC DocumentsNot requiredRequired (ID document + Selfie)
Cardholder NameUp to 27 charsUp to 22 chars (Latin + space only)
AddressBilling + Delivery (for physical)Billing only
Digital WalletsGoogle Pay onlyGoogle Pay & Apple Pay
ATM WithdrawalsAvailable (with PIN)Not available (no SET PIN feature)

Flow Overview

The card issuance process differs between providers:

  • Card Program 1 (CP1): Steps 1 → 2 → 3 → 4 → 8 → 9 → 10
  • Card Program 2 (CP2): All steps

Note: Steps 5-7 (Provide Document Info, Upload ID Document, Upload Selfie) are required for CP2 only and should be skipped for CP1.

Step 1. Retrieve Available Card Offers

Retrieve the available card offers.

Endpoint:

GET /v3/card-offers

📘

V3 Endpoint

This universal endpoint returns offers from both providers. Filter by cardProgram field: CP1 (Card Program 1) or CP2 (Card Program 2).

Response Example

[
    {
        "id": "5f2395c3-5dac-46f7-b7d8-6f8f7c648a24",
        "cardType": "VIRTUAL",
        "cardProgram": "CP2",
        "allowedCardDesigns": [
            {
                "id": "e7afa7cb-92d9-4244-8f3e-595d36d87fc4",
                "name": "BLACK_CP2",
                "color": {
                    "name": "BLACK_CP2",
                    "hexValue": "#191B20"
                }
            }
        ],
        "currentPriceAmount": 2,
        "currentPriceCurrency": "USD",
        "topUpFeePercent": 0.1
    },
    {
        "id": "3c6a1636-9566-4380-9585-9b712f04f6b3",
        "cardType": "VIRTUAL",
        "cardProgram": "CP1",
        "allowedCardDesigns": [
            {
                "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
                "name": "CARD_DESIGN_001_CP1",
                "color": {
                    "name": "ORANGE",
                    "hexValue": "#FC6434"
                }
            },
            {
                "id": "46534fc8-b74d-4a58-967d-ce6224099940",
                "name": "CARD_DESIGN_002_CP1",
                "color": {
                    "name": "BLUE",
                    "hexValue": "#0019FF"
                }
            }
        ],
        "currentPriceAmount": 10,
        "currentPriceCurrency": "USD",
        "topUpFeePercent": 0.1
    },
    {
        "id": "16c74e48-5584-4317-8f3e-04d959cc465d",
        "cardType": "PHYSICAL",
        "cardProgram": "CP1",
        "allowedCardDesigns": [
            {
                "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
                "name": "CARD_DESIGN_003_CP1",
                "color": {
                    "name": "ORANGE",
                    "hexValue": "#FC6434"
                }
            },
            {
                "id": "46534fc8-b74d-4a58-967d-ce6224099940",
                "name": "CARD_DESIGN_004_CP1",
                "color": {
                    "name": "BLUE",
                    "hexValue": "#0019FF"
                }
            }
        ],
        "currentPriceAmount": 10,
        "currentPriceCurrency": "USD",
        "topUpFeePercent": 0.1
    }
]

Step 2. Create a Card Request

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

🔹 For Card Program 1 (CP1)

Endpoint:

POST /v2/card-requests

Request Parameters

ParameterTypeRequiredDescription
cardOfferIduuid✅The unique identifier for the card offer.
cardDesignIduuid✅The unique identifier for the selected card design.
reapDisclaimerAcceptedboolean✅Indicates if the user has accepted the In-App disclaimer.

Request Example

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

Response Example

{
    "id": "801c0a60-d2df-4b9f-b0d9-69fd7040aabc",
    "cardType": "PHYSICAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [],
    "cardDesign": {
        "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
        "name": "CARD_DESIGN_001_CP1",
        "color": {
            "name": "ORANGE",
            "hexValue": "#FC6434"
        }
    },
    "currentPriceAmount": 10,
    "currentPriceCurrency": "USD"
}

🔹 For Card Program 2 (CP2)

Endpoint:

POST /v3/card-requests/cp2

Request Parameters

ParameterTypeRequiredDescription
cardOfferIduuid✅The unique identifier for the card offer.
cardDesignIduuid✅The unique identifier for the selected card design.

Request Example

{
  "cardOfferId": "5f2395c3-5dac-46f7-b7d8-6f8f7c648a24",
  "cardDesignId": "e7afa7cb-92d9-4244-8f3e-595d36d87fc4"
}

No Disclaimer Required (Card Program 2 cards don't require reapDisclaimerAccepted parameter).

Response Example

{
    "id": "435d7941-5238-4579-bc51-cc30a0e4d37d",
    "cardType": "VIRTUAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [],
    "invoiceId": "e2c21d2d-0218-4dee-b4ae-988dfac7ecf4",
    "cardholderName": "",
    "cardDesign": {
        "id": "e7afa7cb-92d9-4244-8f3e-595d36d87fc4",
        "name": "BLACK_CP2",
        "color": {
            "name": "BLACK_CP2",
            "hexValue": "#191B20"
        }
    },
    "currentPriceAmount": 2,
    "currentPriceCurrency": "USD"
}

Possible values for the status field

StatusDescription
DATA_COLLECTIONThe card issuance request has been initiated; the user should now provide all necessary information.
PENDINGRequest pending review.
INVOICE_FAILEDThe invoice payment has failed and can not be processed. User should verify payment details and submit again.

Possible values for the additionalStatuses field

Reflects 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.

For Card Program 1 (CP1):

StatusDescription
CARDHOLDER_NAMEName of the cardholder associated with this request. If the requested card is physical, this name will be printed on the card.
BILLING_ADDRESSBilling address linked to the card request.
DELIVERY_ADDRESSAddress where a physical card will be delivered.
INVOICE_PAIDIndicates whether the user has paid the card issuance.

For Card Program 2 (CP2):

StatusDescription
CARDHOLDER_NAMEName of the cardholder associated with this request. If the requested card is physical, this name will be printed on the card.
BILLING_ADDRESSBilling address linked to the card request.
FRONT_SIDE_IDFront side of ID document uploaded.
BACK_SIDE_IDBack side of ID document uploaded (if required).
DOCUMENT_INFODocument details provided.
SELFIESelfie photo uploaded.
INVOICE_PAIDIndicates whether the user has paid the card issuance.
📘

For virtual cards, the payment invoice ID is generated right after request creation.

For physical cards (Card Program 1 only), it becomes available only after the delivery address is provided.

A card issuance request (for both card providers) can be cancelled via DELETE card-holder/v3/card-requests/{cardRequestId} endpoint with any status except PENDING.

Step 3. Set Cardholder's Name

Provide the cardholder's name.

🔹 For Card Program 1 (CP1)

Endpoint:

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

Path Parameters

ParameterTypeRequiredDescription
cardRequestIdstring✅The unique identifier of the card request.

Body Parameters

ParameterTypeRequiredDescription
cardholderNamestring✅Name of the cardholder to be set on the card.

Request Example

{
  "cardholderName": "John Doe"
}

Response Example

{
    "id": "801c0a60-d2df-4b9f-b0d9-69fd7040aabc",
    "cardType": "PHYSICAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [
        "CARDHOLDER_NAME"
    ],
    "cardholderName": "John Mock-Doe",
    "cardDesign": {
        "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
        "name": "CARD_DESIGN_001_CP1",
        "color": {
            "name": "ORANGE",
            "hexValue": "#FC6434"
        }
    },
    "currentPriceAmount": 10,
    "currentPriceCurrency": "USD"
}

🔹 For Card Program 2 (CP2)

Endpoint:

POST /v3/card-requests/cp2/{cardRequestId}/cardholder-name

Path Parameters

ParameterTypeRequiredDescription
cardRequestIdstring✅The unique identifier of the card request.

Body Parameters

ParameterTypeRequiredDescription
firstNamestring✅User's first name.
lastNamestring✅User's last name.

Request Example

{
  "firstName": "John",
  "lastName": "Doe"
}

Response Example

{
    "id": "435d7941-5238-4579-bc51-cc30a0e4d37d",
    "cardType": "VIRTUAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [
        "CARDHOLDER_NAME"
    ],
    "invoiceId": "e2c21d2d-0218-4dee-b4ae-988dfac7ecf4",
    "cardholderName": "John Doe",
    "cardDesign": {
        "id": "e7afa7cb-92d9-4244-8f3e-595d36d87fc4",
        "name": "BLACK_CP2",
        "color": {
            "name": "BLACK_CP2",
            "hexValue": "#191B20"
        }
    },
    "currentPriceAmount": 2,
    "currentPriceCurrency": "USD"
}
📘

Key Notes

If the requested card type is PHYSICAL, the cardholder name provided in the cardholderName body parameter will be printed on the card.

Cardholder Name Requirements (Card Program 1):

  • 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);
  • for physical cards, first and last names must be separated by a round closing bracket ) (e.g.,John)Doe).

Cardholder Name Requirements (Card Program 2):

  • allowed characters: Latin letters and spaces only (pattern: ^[A-Za-z\s]+$);
  • length limits: up to 22 characters total (combined length of firstName + space + lastName);
  • separate fields: firstName and lastName submitted separately;
  • no special separators required (system combines them automatically).

This endpoint can also update a cardholder’s name.

Step 4. Set Address

Submit the billing and delivery address details.

🔹 For Card Program 1 (CP1)

To retrieve the list of countries whose identification documents are accepted for virtual card issuance, use the Get Countries endpoint.

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

Endpoint:

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

Path Parameters

ParameterTypeRequiredDescription
cardRequestIdstring✅The unique identifier of the card request.

Body Parameters

ParameterTypeRequiredDescription
billingobject✅The address where card bank statements may be sent.
deliveryobject✅Address where a physical card will be delivered — required if the requested card type is PHYSICAL

If the requested card type is PHYSICAL both billing and delivery objects parameters must be provided (including all the required fields).

The delivery parameter fields have character restrictions and limitations. General requirement to all fields except postalCode is that characters are limited to the ASCII range within code points 33 to 122, and ;:!?<>~%^@{}|[]' are not allowed.

Refer to the table below for detailed requirements per field.

FieldRequirement
countryA three-letter country code in ISO 3166-1 alpha-3 format. Must be present in the supported countries list.
cityMaximum length: 20 characters.
addressLine1Maximum length: 50 characters.
addressLine2Maximum length: 50 characters.
firstNameMaximum length: 20 characters.
lastNameMaximum length: 20 characters.
postalCodeMaximum length: 10 characters. Only Latin letters, digits, spaces, and hyphens are allowed.
phoneNumberOnly digits.
dialCodeMust match the shipping country.
stateMaximum length: 35 characters.

Request Example

{
  "billing": {
    "country": "AUT",
    "state": "Vienna",
    "city": "Vienna",
    "addressLine1": "Schweine St",
    "addressLine2": "2",
    "postalCode": "115462"
  },
  "delivery": {
    "country": "AUT",
    "state": "Vienna",
    "city": "Vienna",
    "addressLine1": "Bukhen Wisebier",
    "addressLine2": "62",
    "postalCode": "51552555",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "66565973028",
    "dialCode": "43"
  }
}

Response Example

{
    "id": "801c0a60-d2df-4b9f-b0d9-69fd7040aabc",
    "cardType": "PHYSICAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [
        "CARDHOLDER_NAME",
        "BILLING_ADDRESS",
        "DELIVERY_ADDRESS"
    ],
    "invoiceId": "03118ac7-c971-4e92-8d97-9b0a1bbf7576",
    "cardholderName": "John Doe",
    "billingAddress": {
        "country": "AUT",
        "state": "Vienna",
        "city": "Vienna",
        "addressLine1": "Schweine St",
        "addressLine2": "2",
        "postalCode": "115462"
    },
    "deliveryAddress": {
        "country": "AUT",
        "state": "Vienna",
        "city": "Vienna",
        "addressLine1": "Bukhen Wisebier",
        "addressLine2": "62",
        "postalCode": "51552555",
        "firstName": "John",
        "lastName": "Doe",
        "phone": 66565973028,
        "dialCode": 43
    },
    "cardDesign": {
        "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
        "name": "CARD_DESIGN_001_CP1",
        "color": {
            "name": "ORANGE",
            "hexValue": "#FC6434"
        }
    },
    "currentPriceAmount": 10,
    "currentPriceCurrency": "USD"
}

🔹 For Card Program 2 (CP2)

For Card Program 2 cards, provide billing address only (no delivery address for virtual cards).

Endpoint:

POST /v3/card-requests/cp2/{cardRequestId}/address

Path Parameters

ParameterTypeRequiredDescription
cardRequestIdstring✅The unique identifier of the card request.

Body Parameters

The request body must contain a billingAddress object with the following fields:

FieldTypeRequiredDescription
countrystring✅ISO-2 country code (e.g., "US", "DE", "GB"). Latin characters only.
statestring✅State/province. For USA/Canada: use ISO-2 state code (e.g., "NY", "CA", "ON").
citystring✅City name. Latin letters and spaces only.
addressLine1string✅Address line 1. Latin letters, digits, spaces allowed.
addressLine2string❌Address line 2 (optional).
postalCodestring✅Postal/ZIP code.
📘

Important Notes

  • Country Code: Must be ISO-2 format (2 letters), NOT ISO-3. Examples: "US" (not "USA"), "DE" (not "DEU"), "GB" (not "GBR").
  • State Code for USA/Canada: Must be ISO-2 state code (e.g., "NY" for New York, "CA" for California, "ON" for Ontario). Retrieve the list using Get States endpoint.
  • Supported Countries: Retrieve the list using Get Countries endpoint with filter CP2_VIRTUAL_CARD_ALLOWED.

Request Example

{
  "billingAddress": {
    "country": "DE",
    "state": "Berlin",
    "city": "Berlin",
    "addressLine1": "123 Main Street",
    "addressLine2": "Apt 4B",
    "postalCode": "10001"
  }
}

Response Example

{
    "id": "435d7941-5238-4579-bc51-cc30a0e4d37d",
    "cardType": "VIRTUAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [
        "CARDHOLDER_NAME",
        "BILLING_ADDRESS"
    ],
    "invoiceId": "e2c21d2d-0218-4dee-b4ae-988dfac7ecf4",
    "cardholderName": "John Doe",
    "billingAddress": {
        "country": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "addressLine1": "123 Main Street",
        "addressLine2": "Apt 4B",
        "postalCode": "10001"
    },
    "cardDesign": {
        "id": "e7afa7cb-92d9-4244-8f3e-595d36d87fc4",
        "name": "BLACK_CP2",
        "color": {
            "name": "BLACK_CP2",
            "hexValue": "#191B20"
        }
    },
    "currentPriceAmount": 2,
    "currentPriceCurrency": "USD"
}

Step 5. Provide Document Information

⚠️

Required for Card Program 2 (CP2) only

Submit identity document details for KYC verification.

Endpoint:

POST /v3/card-requests/cp2/{cardRequestId}/document-info

Path Parameters

ParameterTypeRequiredDescription
cardRequestIdstring✅The unique identifier of the card request.

Body Parameters

ParameterTypeRequiredDescription
documentTypestring✅Type of document: PASSPORT, ID_CARD, DRIVING_LICENSE, CN_ID, or HK_ID.
citizenshipstring✅ISO-2 country code of citizenship (e.g., "DE", "US", "GB").
nationalIdstring✅Document number. Allowed: Latin letters, digits, spaces, -/.()
genderstring✅Gender: M (male) or F (female).
issueDatestring✅Issue date (YYYY-MM-DD format). Cannot be in the future.
expiryDatestring✅Expiry date (YYYY-MM-DD format). Cannot be in the past.

Request Example

{
  "documentType": "PASSPORT",
  "citizenship": "DE",
  "nationalId": "12345678",
  "gender": "M",
  "issueDate": "2000-01-27",
  "expiryDate": "2036-01-27"
}

Response Example

{
    "id": "435d7941-5238-4579-bc51-cc30a0e4d37d",
    "cardType": "VIRTUAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [
        "CARDHOLDER_NAME",
        "BILLING_ADDRESS",
        "FRONT_SIDE_ID",
        "DOCUMENT_INFO",
        "BACK_SIDE_ID"
    ],
    "invoiceId": "e2c21d2d-0218-4dee-b4ae-988dfac7ecf4",
    "cardholderName": "John Doe",
    "billingAddress": {
        "country": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "addressLine1": "123 Main Street",
        "addressLine2": "Apt 4B",
        "postalCode": "10001"
    },
    "documentInfo": {
        "documentType": "PASSPORT",
        "citizenship": "DE",
        "nationalId": "12345678",
        "gender": "M",
        "issueDate": "2000-01-27",
        "expiryDate": "2036-01-27"
    },
    "cardDesign": {
        "id": "e7afa7cb-92d9-4244-8f3e-595d36d87fc4",
        "name": "BLACK_CP2",
        "color": {
            "name": "BLACK_CP2",
            "hexValue": "#191B20"
        }
    },
    "currentPriceAmount": 2,
    "currentPriceCurrency": "USD",
    "backSideRequired": false
}
📘

Auto-Set Back Side

When you submit document info, the system returns backSideRequired parameter indicating whether a back side photo is needed. For document types that don't require back side (e.g., PASSPORT, DRIVING_LICENSE), backSideRequired will be false, and BACK_SIDE_ID status will be automatically set.

Step 6. Upload Identity Document Photos

⚠️

Required for Card Program 2 (CP2) only

Upload photos of the identity document for KYC verification.

Endpoint:

POST /v3/card-requests/cp2/{cardRequestId}/kyc-files/{fileType}

Path Parameters

ParameterTypeRequiredDescription
cardRequestIdstring✅The unique identifier of the card request.
fileTypestring✅Type of file being uploaded: FRONT_SIDE or BACK_SIDE (if required).

Supported Document Types

Document TypeRequired Photos
PassportFront side only
ID CardFront side + Back side
Driving LicenceFront side only
Chinese Resident Identity CardFront side + Back side
Hong Kong Identity CardFront side + Back side
📘

Back Side Required?

  • Passport and Driving Licence: Back side not required. Status BACK_SIDE_ID will be auto-set after document info is submitted.
  • ID Card, Chinese ID, Hong Kong ID: Back side required. User must upload both front and back.

File Requirements

  • Format: Image file (JPEG, PNG)
  • Size: Maximum 30 MB
  • Quality: Clear, readable photo of the document

Request Example

Upload front side first:

POST /v3/card-requests/cp2/435d7941-5238-4579-bc51-cc30a0e4d37d/kyc-files/FRONT_SIDE
Content-Type: multipart/form-data

[file binary data]

Then upload back side (if required):

POST /v3/card-requests/cp2/435d7941-5238-4579-bc51-cc30a0e4d37d/kyc-files/BACK_SIDE
Content-Type: multipart/form-data

[file binary data]

Response Example

After uploading front side:

{
    "id": "435d7941-5238-4579-bc51-cc30a0e4d37d",
    "cardType": "VIRTUAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [
        "CARDHOLDER_NAME",
        "BILLING_ADDRESS",
        "FRONT_SIDE_ID"
    ],
    "invoiceId": "e2c21d2d-0218-4dee-b4ae-988dfac7ecf4",
    "cardholderName": "John Doe",
    "billingAddress": {
        "country": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "addressLine1": "123 Main Street",
        "addressLine2": "Apt 4B",
        "postalCode": "10001"
    },
    "cardDesign": {
        "id": "e7afa7cb-92d9-4244-8f3e-595d36d87fc4",
        "name": "BLACK_CP2",
        "color": {
            "name": "BLACK_CP2",
            "hexValue": "#191B20"
        }
    },
    "currentPriceAmount": 2,
    "currentPriceCurrency": "USD"
}

After uploading back side (if required):

{
    "id": "435d7941-5238-4579-bc51-cc30a0e4d37d",
    "cardType": "VIRTUAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [
        "CARDHOLDER_NAME",
        "BILLING_ADDRESS",
        "FRONT_SIDE_ID",
        "BACK_SIDE_ID"
    ],
    "invoiceId": "e2c21d2d-0218-4dee-b4ae-988dfac7ecf4",
    "cardholderName": "John Doe",
    "billingAddress": {
        "country": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "addressLine1": "123 Main Street",
        "addressLine2": "Apt 4B",
        "postalCode": "10001"
    },
    "cardDesign": {
        "id": "e7afa7cb-92d9-4244-8f3e-595d36d87fc4",
        "name": "BLACK_CP2",
        "color": {
            "name": "BLACK_CP2",
            "hexValue": "#191B20"
        }
    },
    "currentPriceAmount": 2,
    "currentPriceCurrency": "USD"
}

Step 7. Upload Selfie

⚠️

Required for Card Program 2 (CP2) only

Upload a selfie photo for identity verification.

Endpoint:

POST /v3/card-requests/cp2/{cardRequestId}/kyc-files/{fileType}

Path Parameters

ParameterTypeRequiredDescription
cardRequestIdstring✅The unique identifier of the card request.
fileTypestring✅Must be SELFIE

File Requirements

  • Format: Image file (JPEG, PNG)
  • Size: Maximum 30 MB
  • Content: Clear photo of user's face
  • Quality: Well-lit, front-facing

Request Example

POST /v3/card-requests/cp2/435d7941-5238-4579-bc51-cc30a0e4d37d/kyc-files/SELFIE
Content-Type: multipart/form-data

[selfie file binary data]

Response Example

{
    "id": "435d7941-5238-4579-bc51-cc30a0e4d37d",
    "cardType": "VIRTUAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [
        "CARDHOLDER_NAME",
        "BILLING_ADDRESS",
        "FRONT_SIDE_ID",
        "BACK_SIDE_ID",
        "DOCUMENT_INFO",
        "SELFIE"
    ],
    "invoiceId": "e2c21d2d-0218-4dee-b4ae-988dfac7ecf4",
    "cardholderName": "John Doe",
    "billingAddress": {
        "country": "DE",
        "state": "Berlin",
        "city": "Berlin",
        "addressLine1": "123 Main Street",
        "addressLine2": "Apt 4B",
        "postalCode": "10001"
    },
    "documentInfo": {
        "documentType": "PASSPORT",
        "citizenship": "DE",
        "nationalId": "12345678",
        "gender": "M",
        "issueDate": "2000-01-27",
        "expiryDate": "2036-01-27"
    },
    "cardDesign": {
        "id": "e7afa7cb-92d9-4244-8f3e-595d36d87fc4",
        "name": "BLACK_CP2",
        "color": {
            "name": "BLACK_CP2",
            "hexValue": "#191B20"
        }
    },
    "currentPriceAmount": 2,
    "currentPriceCurrency": "USD",
    "backSideRequired": false
}
📘

Ready for Payment

Once selfie is uploaded, all KYC steps are complete. The invoiceId is now available for payment.

Step 8. Get Invoice by ID

Endpoint:

GET /acquiring/invoice/{id}

Retrieves an invoice by its ID if it is available for the user.

Path Parameters:

NameTypeRequiredDescription
idstring✅The invoice ID.

Response Example:

{
  "status" : "INIT",
  "payments" : [ ],
  "lastModifiedDate" : "2025-04-22T10:16:56.773584Z",
  "recurrentInvoiceId" : "c2cc3212-7bd5-44f7-a6b0-50ba2beedf11",
  "externalClientId" : "8a7b9019-bec5-4580-9b34-31a0b8fb613f",
  "id" : "8ff3635a-0f80-40a1-8eb3-555802c0635d",
  "amount" : 3,
  "currency" : "usd",
  "type" : "ORIGINAL",
  "alignable" : true
}

Optional. Apply Discount to Invoice

Endpoint:

PUT /acquiring/invoice/{invoiceId}/discount

Enables clients to apply promotional discounts before finalizing the payment.

Path Parameters:

NameTypeRequiredDescription
invoiceIdstring✅The invoice ID.

Query Parameters:

NameTypeRequiredDescription
discountCodestring✅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 9. Initialize Payment

Endpoint:

POST /invoice/payment

Initializes the payment for the card.

Body Parameters:

NameTypeRequiredDescription
invoiceIdstring✅The invoice ID.
typestring✅Payment provider type (only PLATFORM one is available).
accountIdstring✅Identifies the CHECKING type of account in the wallet service. All accounts can be retrieved using List all accounts endpoint.
currencystring✅Currency used for the payment.
anyCurrencyboolean✅Flag indicating whether multiple currencies are supported.
📘

Supported Currencies for Card Payment

Use only currencies that support card issuance for the selected card program (CP1 or CP2). Check settings.features array in Get All Currencies response. See Supported Features for details.

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 10. Confirm Invoice Payment

Endpoint:

POST /payment/pay

Confirms the payment of the invoice.

Body Parameters:

NameTypeRequiredDescription
invoiceIdstring✅The invoice ID.
typestring✅Payment provider type (only PLATFORM one is available).
paymentIdstring✅Unique identifier for the payment from Step 9.
accountIdstring✅Identifies the CHECKING type of account in the wallet service. All accounts can be retrieved using List all accounts endpoint.
currencystring✅Currency used for the payment.
anyCurrencyboolean✅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"
}

After submitting all required data, the application is automatically sent to the partner for review, and its status changes to PENDING.

❗️

If the partner declines the card issuance, neither the card fee nor the shipping fee is refunded.

Card Issuance Completion

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.

📧

Notification

After card approval, the user receives:

  • Push notification
  • Email notification

Card Statuses

The List All Cards endpoint also retrieves the possible statuses of issued bank cards:

StatusDescription
ACTIVEThe card has been successfully issued. The user can utilize all its functions.
FROZENThe card has been frozen by the user. The user can unfreeze it at their discretion by using the Change Card Status endpoint.
BLOCKEDThe card has been automatically blocked by the system (e.g., after 3 incorrect PIN attempts) or by the FCO. The user should contact our support team in order to unblock the card.
EXPIREDThe card has expired. It must be reissued.

Available Card Operations

Once the card is issued, the following operations are available:

For Card Program 1 (CP1):

  • Top Up: Fund card using cryptocurrency (check CARD_TOP_UP feature)
  • View Details: Get card sensitive details (PAN, CVV, expiry)
  • Freeze/Unfreeze: Temporarily block/unblock card
  • Set/Reset PIN: Manage card PIN for ATM withdrawals
  • ATM Withdrawals: Available with PIN
  • Add to Google Pay: Digital wallet integration
  • Transaction History: View card transaction history

For Card Program 2 (CP2):

  • Top Up: Fund card using cryptocurrency (check CP2_TOP_UP feature)
  • View Details: Get card sensitive details (PAN, CVV, expiry)
  • Freeze/Unfreeze: Temporarily block/unblock card
  • Add to Google Pay & Apple Pay: Digital wallet integration
  • No PIN Feature: ATM withdrawals not available for virtual cards
  • Transaction History: Coming soon (separate implementation)

Updated about 23 hours ago