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"
                }
            }
        ],
        "currentPriceAmount": 10,
        "currentPriceCurrency": "USD"
    }

Step 2: Create a Card Request

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

Endpoint:

POST /v2/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": "801c0a60-d2df-4b9f-b0d9-69fd7040aabc",
    "cardType": "PHYSICAL",
    "status": "DATA_COLLECTION",
    "additionalStatuses": [],
    "cardDesign": {
        "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
        "name": "ALLA_GORBUNOVA_SA_USD_REAP",
        "color": {
            "name": "ORANGE",
            "hexValue": "#FC6434"
        }
    },
    "currentPriceAmount": 10,
    "currentPriceCurrency": "USD"
}

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. If the requested card is physical, this name will be printed on the card.
`BILLING_ADDRESS`	Billing address linked to the card request.
`DELIVERY_ADDRESS`	Address where a physical card will be delivered.
`INVOICE_PAID`	Indicates wether the user has paid the card issuance.

📘
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": "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": "ALLA_GORBUNOVA_SA_USD_REAP",
        "color": {
            "name": "ORANGE",
            "hexValue": "#FC6434"
        }
    },
    "currentPriceAmount": 10,
    "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:

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

This endpoint can also update a cardholder’s name.

Step 4: Set Address

Submit the billing and delivery address details.

To retrieve the list of countries where virtual cards are available, 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

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	✅	Address where a physical card will be delivered — required if the requested card type is`PHYSICAL`

If the requested card type isPHYSICAL both billing and deliveryobjects parameters must be put in (including all the required fields).

The delivery parameter fields have got 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.

Field	Requirement
`country`	A three-letter country code in ISO 3166-1 alpha-3 format. Must be present in the supported countries list.
`city`	Maximum length: 20 characters.
`addressLine1`	Maximum length: 50 characters.
`addressLine2`	Maximum length: 50 characters.
`firstName`	Maximum length: 20 characters.
`lastName`	Maximum length: 20 characters.
`postalCode`	Maximum length: 10 characters. Only Latin letters, digits, spaces, and hyphens are allowed.
`phoneNumber`	Only digits.
`dialCode`	Must match the shipping country.
`state`	Maximum length: 35 characters.

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": "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 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": 66565973028,
        "dialCode": 43
    },
    "cardDesign": {
        "id": "f20c82e2-b44d-42e8-aa8a-bae9c1a266ff",
        "name": "ALLA_GORBUNOVA_SA_USD_REAP",
        "color": {
            "name": "ORANGE",
            "hexValue": "#FC6434"
        }
    },
    "currentPriceAmount": 10,
    "currentPriceCurrency": "USD"
}

Step 5. Get Invoice by ID

Endpoint:

GET /acquiring/invoice/{id}

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

Path Parameters:

Name	Type	Required	Description
`id`	`string`	✅	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:

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 6. 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 7. 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"
}

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

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.

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

Step 5. Get Invoice by ID

Endpoint:

Path Parameters:

Response Example:

Optional. Apply Discount to Invoice

Endpoint:

Path Parameters:

Query Parameters:

Response Example:

Step 6. Initialize Payment

Endpoint:

Body Parameters:

Response Example:

Step 7. Confirm Invoice Payment

Endpoint:

Body Parameters:

Response Example:

Possible values for the `STATUS` field

Possible values for the `additionalStatuses` field

📘
Key Notes