Verify OTP and complete card replacement

Verifies the OTP and completes the card replacement process. On success, the old card is
cancelled and the new replacement card is returned.

Request:

session_id: Session ID from the replacement initiation

otp: 4-digit OTP code sent to the customer

Response:

card: The new replacement card details

delivery_address: Delivery address (only for physical cards)

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_INVALID: Invalid OTP provided

404 CARD_NOT_FOUND: Card does not exist

404 OTP_OPERATION_NOT_FOUND: Session ID not found

412 INVALID_CARD_STATUS: Card is not in ACTIVE status

412 OTP_OPERATION_WRONG_STATUS: OTP operation is not in correct state

503 SERVICE_UNAVAILABLE: Service temporarily unavailable

503 INVALID_CARD: Card replacement failed (Paymentology error)

Responses

🟢200OK

application/json

Default Response

Body

🟠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

curl --location --request POST 'https://api.staging.vrtx.sa/cards/replacement/verify-otp' \ --header 'Content-Type: application/json' \ --data-raw '{ "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82", "otp": "stri" }'

{ "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" } }