Phone Number

When you onboard as a partner, you choose whether your users must prove they own a phone number with an SMS one-time password (OTP) before that number is stored. That choice is set during onboarding; you cannot change it yourself later. If you are unsure which mode you are on, ask your Gnosis Pay contact. Use GET /phone to read the stored phone and countryCode. This page documents both modes so you can follow the path that matches how you onboarded.

If you do not require phone OTP for your users

Pass the number in E.164 format as phone on the first POST /cards/virtual. That is how the phone is set. See Create Virtual Card.

If you require phone OTP for your users

Users must verify the number with SMS before it is stored.

Onboarding

Phone verification is the last step of onboarding. GET /user/onboarding stays action_verify_phone until the phone is verified. Completing the OTP flow with POST /phone moves the status to completed. See Onboard to Gnosis Pay. Requesting an OTP (and setting the phone the first time with POST /phone) requires KYC approved and an active account. Otherwise the API returns 422 KYC_NOT_APPROVED or 422 ACCOUNT_NOT_READY.

Add a verified phone

Send an OTP

Call POST /phone/verification with the number in E.164 format. The user receives a 6-digit SMS code. Codes expire; requesting another code too soon returns 422 PHONE_OTP_RESEND_TOO_SOON.

Sandbox
Production

cURL

curl --request POST \
  --url https://core.sandbox.gnosispay.in/user-api/phone/verification \
  --header 'Content-Type: application/json' \
  --data '{
    "phone": "+441234567890"
  }'

cURL

curl --request POST \
  --url https://core.prod.gnosispay.com/user-api/phone/verification \
  --header 'Content-Type: application/json' \
  --data '{
    "phone": "+441234567890"
  }'

Confirm the code

Call POST /phone with { "code": "<6 digits>" }. phone is optional here; the number stored is the one that received the SMS. Omitting code returns 409 PHONE_VERIFICATION_REQUIRED.

Sandbox
Production

cURL

curl --request POST \
  --url https://core.sandbox.gnosispay.in/user-api/phone \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "123456"
  }'

cURL

curl --request POST \
  --url https://core.prod.gnosispay.com/user-api/phone \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "123456"
  }'

Change a verified phone

Request a new OTP with POST /phone/verification, then confirm with PATCH /phone and { "code": "<6 digits>" }. PATCH only updates an existing number: if the user has no phone yet, the response is 404 and the OTP is not consumed.

Change a phone without verification

Call PATCH /phone with the new number in E.164 format and omit code. If the user has no phone yet, the response is 404.

If you require phone OTP for your users, this call fails with 409 PHONE_VERIFICATION_REQUIRED. Use the OTP change flow above instead.

Sandbox
Production

cURL

curl --request PATCH \
  --url https://core.sandbox.gnosispay.in/user-api/phone \
  --header 'Content-Type: application/json' \
  --data '{
    "phone": "+441234567890"
  }'

cURL

curl --request PATCH \
  --url https://core.prod.gnosispay.com/user-api/phone \
  --header 'Content-Type: application/json' \
  --data '{
    "phone": "+441234567890"
  }'

Error codes

Code	Typical status	When
`PHONE_VERIFICATION_NOT_REQUIRED`	422	You called `POST /phone/verification` but you did not require phone OTP for your users
`PHONE_OTP_NOT_REQUIRED`	400	You sent `code` on a write but you did not require phone OTP for your users
`PHONE_VERIFICATION_REQUIRED`	409	You omitted `code` on a write, or tried to create a first card before the phone was verified, while you require phone OTP for your users
`KYC_NOT_APPROVED`	422	OTP send or first `POST /phone` before KYC is approved
`ACCOUNT_NOT_READY`	422	OTP send or first `POST /phone` before the account is active
`INVALID_OTP`	400	Wrong code
`OTP_EXPIRED`	400	Code expired
`OTP_NOT_DELIVERED`	400	No delivered challenge to consume
`PHONE_OTP_RESEND_TOO_SOON`	422	Another OTP was requested too recently
`PHONE_OTP_DELIVERY_FAILED`	502	SMS delivery failed

Getting started

Authentication & Onboarding

KYC Sharing

Manage Accounts

Manage Cards

Secure Card Elements via PSE

Webhooks

If you do not require phone OTP for your users

If you require phone OTP for your users

Onboarding

Add a verified phone

Change a verified phone

Change a phone without verification

Error codes

​If you do not require phone OTP for your users

​If you require phone OTP for your users

​Onboarding

​Add a verified phone

​Change a verified phone

​Change a phone without verification

​Error codes

If you do not require phone OTP for your users

If you require phone OTP for your users

Onboarding

Add a verified phone

Change a verified phone

Change a phone without verification

Error codes