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, providing necessary details, and completing the payment.

Step 1: Retrieve Available Card Offers

Retrieve the available card offers using the List Card Offers endpoint.

Endpoint Details

Method: GET
URL: /v1/card-offers

Response Example

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "cardType": "VIRTUAL",
    "allowedCardDesigns": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string",
        "color": {
          "name": "string",
          "hexValue": "string"
        }
      }
    ],
    "currentPriceAmount": 0,
    "currentPriceCurrency": "string"
  }
]

Step 2: Create a Card Request

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

Endpoint Details

Method: POST
URL: /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": "string",
  "cardType": "VIRTUAL",
  "status": "DATA_COLLECTION",
  "invoiceId": "string",
  "cardholderName": "string"
}

Step 3: Update Cardholder Name

Provide the cardholder's name using the Update Cardholder Name endpoint.

Request Parameters

Parameter	Type	Required	Description
`cardholderName`	string	✅	The name to be printed on the card.

Request Example

{
  "cardholderName": "John Doe"
}

Step 4: Update Billing Address

Submit the billing address details using the Update Billing Address endpoint.

Request Parameters

Parameter	Type	Required	Description
`country`	string	✅	Country of the billing address.
`state`	string	❌	State/region of the billing address.
`city`	string	✅	City of the billing address.
`addressLine1`	string	✅	Primary address line.
`addressLine2`	string	❌	Secondary address line.
`postalCode`	string	✅	Postal code of the billing address.

Request Example

{
  "country": "string",
  "state": "string",
  "city": "string",
  "addressLine1": "string",
  "addressLine2": "string",
  "postalCode": "string"
}

Step 5: Invoice Payment Get or Create

This endpoint retrieves an existing payment or creates a new payment for an invoice.

Endpoint Details

Method: POST
URL: /invoice/payment

Request Parameters

Parameter	Type	Required	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	❌	Currency used for the payment.
`anyCurrency`	boolean	✅	Flag indicating whether multiple currencies are allowed.

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 6: Confirm Invoice Payment

This endpoint confirms the payment for an invoice.

Endpoint Details

Method: POST
URL: /invoice/payment/pay

Request Parameters

Parameter	Type	Required	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	❌	Currency used for the payment.
`anyCurrency`	boolean	✅	Flag indicating whether multiple currencies are allowed.

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
}

Step 7: Cancel Card Request (If Necessary)

Endpoint

Method: DELETE
URL: /v1/card-requests/{cardRequestId}

Description

This endpoint allows users to cancel a pending card request. The cardRequestId must be valid and correspond to an active request. If the request is already processed, cancellation may not be possible.

Request Parameters

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

Response

200 OK – Card request successfully deleted.

Request Example

DELETE /v1/card-requests/3fa85f64-5717-4562-b3fc-2c963f66afa6 HTTP/1.1
Host: platform-api.dev.testessential.net
Authorization: Bearer YOUR_ACCESS_TOKEN