Endpoints for verifying a customer's email and phone via one-time codes. Required only for customers whose payment provider mandates contact verification (e.g. EU customers); other providers return 409.
openapi: 3.1.0
info:
title: Grid Agent Management Contact Verification API
description: 'API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/.
'
version: '2025-10-13'
contact:
name: Lightspark Support
email: support@lightspark.com
license:
name: Proprietary
url: https://lightspark.com/terms
servers:
- url: https://api.lightspark.com/grid/2025-10-13
description: Production server
security:
- BasicAuth: []
- AgentAuth: []
tags:
- name: Contact Verification
description: Endpoints for verifying a customer's email and phone via one-time codes. Required only for customers whose payment provider mandates contact verification (e.g. EU customers); other providers return 409.
paths:
/customers/{customerId}/verify-email:
parameters:
- name: customerId
in: path
description: The Grid customer ID to send an email verification code to.
required: true
schema:
type: string
post:
summary: Send an email verification code to a customer
description: 'Send (or resend) a one-time code to the customer''s email address to begin
email verification.
This endpoint is only meaningful for customers whose payment provider
requires contact verification (e.g. EU customers); the customer''s
`contactVerification.email` status reflects progress. For customers whose
provider has no such requirement, this returns `409`.
Call `POST /customers/{customerId}/verify-email/confirm` with the received
code to complete verification. Re-POST this endpoint to resend the code.
In sandbox, no email is sent and the code is always `123456`.
'
operationId: sendCustomerEmailVerification
tags:
- Contact Verification
security:
- BasicAuth: []
responses:
'204':
description: Verification code sent.
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: The customer's payment provider does not require contact verification, or the email is already verified.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/customers/{customerId}/verify-email/confirm:
parameters:
- name: customerId
in: path
description: The Grid customer ID whose email is being verified.
required: true
schema:
type: string
post:
summary: Confirm a customer's email verification code
description: 'Submit the one-time code the customer received by email to mark their email
as `VERIFIED`. On success, `contactVerification.email` becomes `VERIFIED`.
Both email and phone must be `VERIFIED` before the customer can begin KYC.
In sandbox, the code is always `123456`.
'
operationId: confirmCustomerEmailVerification
tags:
- Contact Verification
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactVerificationConfirmRequest'
responses:
'200':
description: Email verified.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'400':
description: Invalid or expired code
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: The customer's payment provider does not require contact verification, or the email is already verified.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/customers/{customerId}/verify-phone:
parameters:
- name: customerId
in: path
description: The Grid customer ID to send a phone verification code to.
required: true
schema:
type: string
post:
summary: Send a phone verification code to a customer
description: 'Send (or resend) a one-time code via SMS to the customer''s phone number to
begin phone verification.
This endpoint is only meaningful for customers whose payment provider
requires contact verification (e.g. EU customers); the customer''s
`contactVerification.phone` status reflects progress. For customers whose
provider has no such requirement, this returns `409`.
Call `POST /customers/{customerId}/verify-phone/confirm` with the received
code to complete verification. Re-POST this endpoint to resend the code.
In sandbox, no SMS is sent and the code is always `123456`.
'
operationId: sendCustomerPhoneVerification
tags:
- Contact Verification
security:
- BasicAuth: []
responses:
'204':
description: Verification code sent.
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: The customer's payment provider does not require contact verification, or the phone is already verified.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
/customers/{customerId}/verify-phone/confirm:
parameters:
- name: customerId
in: path
description: The Grid customer ID whose phone is being verified.
required: true
schema:
type: string
post:
summary: Confirm a customer's phone verification code
description: 'Submit the one-time code the customer received via SMS to mark their phone
as `VERIFIED`. On success, `contactVerification.phone` becomes `VERIFIED`.
Both email and phone must be `VERIFIED` before the customer can begin KYC.
In sandbox, the code is always `123456`.
'
operationId: confirmCustomerPhoneVerification
tags:
- Contact Verification
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactVerificationConfirmRequest'
responses:
'200':
description: Phone verified.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'400':
description: Invalid or expired code
content:
application/json:
schema:
$ref: '#/components/schemas/Error400'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error404'
'409':
description: The customer's payment provider does not require contact verification, or the phone is already verified.
content:
application/json:
schema:
$ref: '#/components/schemas/Error409'
'500':
description: Internal service error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
components:
schemas:
Error400:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 400
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| INVALID_INPUT | Invalid input provided |
| MISSING_MANDATORY_USER_INFO | Required customer information is missing |
| INVITATION_ALREADY_CLAIMED | Invitation has already been claimed |
| INVITATIONS_NOT_CONFIGURED | Invitations are not configured |
| INVALID_UMA_ADDRESS | UMA address format is invalid |
| INVITATION_CANCELLED | Invitation has been cancelled |
| QUOTE_REQUEST_FAILED | An issue occurred during the quote process; this is retryable |
| INVALID_PAYREQ_RESPONSE | Counterparty Payreq response was invalid |
| INVALID_RECEIVER | Receiver is invalid |
| PARSE_PAYREQ_RESPONSE_ERROR | Error parsing receiver PayReq response |
| CERT_CHAIN_INVALID | Counterparty certificate chain is invalid |
| CERT_CHAIN_EXPIRED | Counterparty certificate chain has expired |
| INVALID_PUBKEY_FORMAT | Counterparty Public key format is invalid |
| MISSING_REQUIRED_UMA_PARAMETERS | Counterparty required UMA parameters are missing |
| SENDER_NOT_ACCEPTED | Sender is not accepted |
| AMOUNT_OUT_OF_RANGE | Amount is out of range |
| INVALID_CURRENCY | Currency is invalid |
| INVALID_TIMESTAMP | Timestamp is invalid |
| INVALID_NONCE | Nonce is invalid |
| INVALID_REQUEST_FORMAT | Request format is invalid |
| INVALID_BANK_ACCOUNT | Bank account is invalid |
| SELF_PAYMENT | Self payment not allowed |
| LOOKUP_REQUEST_FAILED | Lookup request failed |
| PARSE_LNURLP_RESPONSE_ERROR | Error parsing LNURLP response |
| INVALID_AMOUNT | Amount is invalid |
| WEBHOOK_ENDPOINT_NOT_SET | Webhook endpoint is not set |
| WEBHOOK_DELIVERY_ERROR | Webhook delivery error |
| LOW_QUALITY | Document quality too low to process |
| DATA_MISMATCH | Document details don''t match provided information |
| EXPIRED | Document has expired |
| SUSPECTED_FRAUD | Document suspected of being forged or edited |
| UNSUITABLE_DOCUMENT | Document type is not accepted or not supported |
| INCOMPLETE | Document is missing pages or sides |
| EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS | An EMAIL_OTP credential is already registered on the target internal account; only one email OTP credential is supported per internal account at this time |
| SMS_OTP_CREDENTIAL_ALREADY_EXISTS | An SMS_OTP credential is already registered on the target internal account; only one SMS OTP credential is supported per internal account at this time |
| PASSKEY_CREDENTIAL_ALREADY_EXISTS | A PASSKEY credential with the same WebAuthn credentialId is already registered on the target internal account |
| STABLECOIN_PROVIDER_ACCOUNT_INVALID | The stablecoin provider account link is not usable |
| STABLECOIN_PROVIDER_ACCOUNT_REVOKED | The stablecoin provider account link has been revoked |
| STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED | Multiple active provider account links exist; pass `stablecoinProviderAccountId` to select one |
'
enum:
- INVALID_INPUT
- MISSING_MANDATORY_USER_INFO
- INVITATION_ALREADY_CLAIMED
- INVITATIONS_NOT_CONFIGURED
- INVALID_UMA_ADDRESS
- INVITATION_CANCELLED
- QUOTE_REQUEST_FAILED
- INVALID_PAYREQ_RESPONSE
- INVALID_RECEIVER
- PARSE_PAYREQ_RESPONSE_ERROR
- CERT_CHAIN_INVALID
- CERT_CHAIN_EXPIRED
- INVALID_PUBKEY_FORMAT
- MISSING_REQUIRED_UMA_PARAMETERS
- SENDER_NOT_ACCEPTED
- AMOUNT_OUT_OF_RANGE
- INVALID_CURRENCY
- INVALID_TIMESTAMP
- INVALID_NONCE
- INVALID_REQUEST_FORMAT
- INVALID_BANK_ACCOUNT
- SELF_PAYMENT
- LOOKUP_REQUEST_FAILED
- PARSE_LNURLP_RESPONSE_ERROR
- INVALID_AMOUNT
- WEBHOOK_ENDPOINT_NOT_SET
- WEBHOOK_DELIVERY_ERROR
- LOW_QUALITY
- DATA_MISMATCH
- EXPIRED
- SUSPECTED_FRAUD
- UNSUITABLE_DOCUMENT
- INCOMPLETE
- EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS
- SMS_OTP_CREDENTIAL_ALREADY_EXISTS
- PASSKEY_CREDENTIAL_ALREADY_EXISTS
- STABLECOIN_PROVIDER_ACCOUNT_INVALID
- STABLECOIN_PROVIDER_ACCOUNT_REVOKED
- STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
ContactVerification:
type: object
description: 'Email and/or phone verification state for the customer. This object is **only present when the customer''s regulatory jurisdiction requires contact verification** (e.g. EU customers). For customers who have no such requirement, this object is omitted entirely — no action is needed.
Each channel is reported independently: only the channels the customer''s provider actually requires are present. A provider may require both email and phone, just one of them, or — when the object is absent — neither. Every channel that **is** present must reach `VERIFIED` before the customer can begin KYC. Drive each present channel with `POST /customers/{customerId}/verify-email` and/or `POST /customers/{customerId}/verify-phone` (and their `/confirm` sub-routes).'
properties:
email:
$ref: '#/components/schemas/ContactVerificationStatus'
description: Verification status of the customer's email address. Present only when the provider requires email verification.
phone:
$ref: '#/components/schemas/ContactVerificationStatus'
description: Verification status of the customer's phone number. Present only when the provider requires phone verification.
Customer:
type: object
required:
- umaAddress
- platformCustomerId
- customerType
properties:
id:
type: string
description: System-generated unique identifier
readOnly: true
example: Customer:019542f5-b3e7-1d02-0000-000000000001
platformCustomerId:
type: string
description: Platform-specific customer identifier
example: 9f84e0c2a72c4fa
customerType:
$ref: '#/components/schemas/CustomerType'
region:
type: string
description: Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.
example: US
currencies:
type: array
items:
type: string
description: List of currency codes enabled for this customer.
example:
- USD
- USDC
email:
type: string
format: email
description: Email address for the customer.
example: john.doe@example.com
phoneNumber:
type: string
pattern: ^\+[1-9]\d{1,14}$
description: Phone number for the customer in strict E.164 format.
example: '+14155551234'
umaAddress:
type: string
description: Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
example: $john.doe@uma.domain.com
createdAt:
type: string
format: date-time
description: Creation timestamp
readOnly: true
example: '2025-07-21T17:32:28Z'
updatedAt:
type: string
format: date-time
description: Last update timestamp
readOnly: true
example: '2025-07-21T17:32:28Z'
isDeleted:
type: boolean
description: Whether the customer is marked as deleted
example: false
readOnly: true
contactVerification:
allOf:
- $ref: '#/components/schemas/ContactVerification'
readOnly: true
description: Email and phone verification state. **Only present when the customer's payment provider requires it** (e.g. EU customers); omitted otherwise.
Error409:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 409
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL | Transaction is not pending platform approval |
| UMA_ADDRESS_EXISTS | UMA address already exists |
| EMAIL_OTP_EMAIL_ALREADY_EXISTS | Email address is already associated with an EMAIL_OTP credential |
| EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued |
| PASSKEY_ALREADY_ENROLLED | The customer already has an enrolled passkey factor; only one passkey per customer is supported. Delete the existing one before enrolling another |
| CONFLICT | Generic resource-state conflict. Returned, for example, when `platformCustomerId` on a customer create call collides with an existing active customer on the same platform |
'
enum:
- TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL
- UMA_ADDRESS_EXISTS
- EMAIL_OTP_EMAIL_ALREADY_EXISTS
- EMAIL_OTP_CREDENTIAL_SET_CHANGED
- PASSKEY_ALREADY_ENROLLED
- CONFLICT
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
CustomerType:
type: string
enum:
- INDIVIDUAL
- BUSINESS
description: Whether the customer is an individual or a business entity
example: INDIVIDUAL
Error500:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 500
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| GRID_SWITCH_ERROR | Grid switch error |
| INTERNAL_ERROR | Internal server or UMA error |
'
enum:
- GRID_SWITCH_ERROR
- INTERNAL_ERROR
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
ContactVerificationConfirmRequest:
type: object
description: Request body for confirming an email or phone verification challenge.
required:
- code
properties:
code:
type: string
description: The one-time verification code the customer received via email or SMS. In sandbox, the code is always `123456`.
example: '123456'
ContactVerificationStatus:
type: string
description: Status of an individual contact-verification channel (email or phone). `PENDING` means verification is required but not yet completed; `VERIFIED` means the channel has been confirmed.
enum:
- PENDING
- VERIFIED
example: VERIFIED
Error401:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 401
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| UNAUTHORIZED | Issue with API credentials |
| INVALID_SIGNATURE | Signature header is invalid |
| WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied |
| WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) |
| WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received |
| WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential |
| REQUEST_ID_MISSING | The `Request-Id` header is required on the signed retry but was not supplied (paired with `Grid-Wallet-Signature`) |
'
enum:
- UNAUTHORIZED
- INVALID_SIGNATURE
- WALLET_SIGNATURE_MISSING
- WALLET_SIGNATURE_MALFORMED
- WALLET_SIGNATURE_BODY_MISMATCH
- WALLET_SIGNATURE_INVALID
- REQUEST_ID_MISSING
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
Error404:
type: object
required:
- message
- status
- code
properties:
status:
type: integer
enum:
- 404
description: HTTP status code
code:
type: string
description: '| Error Code | Description |
|------------|-------------|
| TRANSACTION_NOT_FOUND | Transaction not found |
| INVITATION_NOT_FOUND | Invitation not found |
| USER_NOT_FOUND | Customer not found |
| QUOTE_NOT_FOUND | Quote not found |
| LOOKUP_REQUEST_NOT_FOUND | Lookup request not found |
| TOKEN_NOT_FOUND | Token not found |
| BULK_UPLOAD_JOB_NOT_FOUND | Bulk upload job not found |
| REFERENCE_NOT_FOUND | Reference not found |
| UMA_NOT_FOUND | The UMA address is well-formed but no receiver exists at the counterparty VASP |
| STABLECOIN_PROVIDER_ACCOUNT_NOT_FOUND | Stablecoin provider account link not found |
'
enum:
- TRANSACTION_NOT_FOUND
- INVITATION_NOT_FOUND
- USER_NOT_FOUND
- QUOTE_NOT_FOUND
- LOOKUP_REQUEST_NOT_FOUND
- TOKEN_NOT_FOUND
- BULK_UPLOAD_JOB_NOT_FOUND
- REFERENCE_NOT_FOUND
- UMA_NOT_FOUND
- STABLECOIN_PROVIDER_ACCOUNT_NOT_FOUND
message:
type: string
description: Error message
details:
type: object
description: Additional error details
additionalProperties: true
securitySchemes:
BasicAuth:
type: http
scheme: basic
description: API token authentication using format `<api token id>:<api client secret>`
AgentAuth:
type: http
scheme: bearer
description: 'Bearer token authentication for agent-scoped endpoints. The token is the `accessToken` returned when redeeming a device code via `POST /agents/device-codes/{code}/redeem`. Agent credentials are user-scoped: all requests are automatically bound to the agent''s associated customer and subject to the agent''s policy.'
WebhookSignature:
type: apiKey
in: header
name: X-Grid-Signature
description: 'Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by Grid.
To verify the signature:
1. Get the Grid public key provided to you during integration
2. Decode the base64 signature from the header
3. Create a SHA-256 hash of the request body
4. Verify the signature using the public key and the hash
If the signature verification succeeds, the webhook is authentic. If not, it should be rejected.
'