vrtx Docs
Core APIs
  • Start
  • Onboarding
  • Wallet
  • Payouts
  • Cards
  • Transactions
Closed loop APIsCard Simulator
SDK APIs
  • Coming Soon!
Core APIs
  • Start
  • Onboarding
  • Wallet
  • Payouts
  • Cards
  • Transactions
Closed loop APIsCard Simulator
SDK APIs
  • Coming Soon!
  1. Issuance
  • Issuance
    • Issue card
      POST
    • Get card issuance
      GET
    • Complete card issuance
      POST
    • Verify card issuance OTP
      POST
    • Convert virtual to physical
      POST
    • Verify card conversion OTP
      POST
  • Management
    • Get card
      GET
    • Change card status
      PATCH
    • Set or update card PIN
      POST
    • Verify card PIN OTP
      POST
    • Activate physical card
      POST
    • Verify activation OTP
      POST
    • Display sensitive data
      POST
    • Verify display sensitive data OTP
      POST
  1. Issuance

Verify card conversion OTP

POST
https://api.staging.vrtx.sa/cards/complete-conversion
Last modified:2025-12-03 10:51:05
Completes the virtual to physical card conversion by verifying the OTP sent during the initiation step.
On success, the card is converted to physical and delivery address information is returned.
Request:
session_id: Session ID (cardIssuanceId) from the convert request
otp: 4-digit OTP code sent to the customer
Response:
card: Updated card with physical card details
delivery_address: Delivery address for the physical card
Error Responses:
400 INVALID_INPUT: Invalid request body
400 INVALID_OTP_FORMAT: OTP format is invalid (must be 4 digits)
400 OTP_EXPIRED: OTP has expired
400 OTP_MAX_ATTEMPTS_REACHED: Maximum OTP verification attempts reached
400 OTP_VERIFICATION_FAILED: OTP verification failed (generic error)
400 OTP_INCORRECT: Invalid OTP provided
404 CARD_NOT_FOUND: Card does not exist
404 CARD_ISSUANCE_NOT_FOUND: Card issuance session not found
404 OTP_OPERATION_NOT_FOUND: OTP operation context missing
409 CARD_TYPE_CONFLICT: Card is already physical
412 CARD_STATUS_NOT_ALLOWED: Card is not in ACTIVE status
412 INVALID_CARD_STATUS: Card status is invalid for this operation
412 OTP_OPERATION_WRONG_STATUS: OTP operation is not in correct state
503 SERVICE_UNAVAILABLE: Service temporarily unavailable

Request

Authorization
JWT Bearer
Add the parameter
Authorization
to Headers
Example:
Authorization: ********************
or
Body Params application/jsonRequired

Example
{
    "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
    "otp": "stri"
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.staging.vrtx.sa/cards/complete-conversion' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
    "otp": "stri"
}'

Responses

🟢200OK
application/json
Default Response
Body

Example
{
    "card": {
        "id": "f5a4b3c2-d1e0-9876-5432-1a0b9c8d7e6f",
        "account_id": "b2c3d4e5-f6a7-5890-b123-c4d5e6f7a8b9",
        "token": 987654321,
        "status": "LOCKED",
        "last_4_digits": "8765",
        "expiry_date": "2026-06-30",
        "design": "premium",
        "created_at": "2023-12-01T08:15:00Z",
        "updated_at": "2024-01-10T14:20:00Z",
        "is_physical": true,
        "physical_card_activation_status": "ACTIVATED",
        "physical_activated_at": "2024-02-01T09:00:00Z"
    },
    "delivery_address": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "city": "string",
        "country": "string",
        "mobile_number": "string"
    }
}
đźź 400Bad Request
đźź 401Unauthorized
đźź 403Forbidden
đźź 404Not Found
đźź 405Method Not Allowed
đźź 409Conflict
đźź 410Gone
đźź 412Precondition Failed
đźź 422Unprocessable Entity
đźź 429Too Many Requests
đź”´500Internal Server Error
đź”´501Not Implemented
đź”´503Service Unavailable
đź”´504Gateway Timeout
đź”´505HTTP Version Not Supported
Modified at 2025-12-03 10:51:05
Previous
Convert virtual to physical
Next
Get card
Built with