diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index a73b3fd7..f5aff089 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -21,6 +21,8 @@ tags: description: Platform configuration endpoints for managing global settings. You can also configure these settings in the Grid dashboard. - name: Customers description: Customer management endpoints for creating and updating customer information + - 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. - name: KYC/KYB Verifications description: Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) verification, including managing beneficial owners and triggering verification for customers. - name: Documents @@ -843,6 +845,252 @@ paths: application/json: schema: $ref: '#/components/schemas/Error404' + '409': + description: The customer's payment provider requires contact verification and the customer's email and phone are not both `VERIFIED` yet. Complete contact verification (see `verify-email` and `verify-phone`) before generating a KYC link. + 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: + 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: @@ -8579,6 +8827,26 @@ components: - BUSINESS description: Whether the customer is an individual or a business entity example: INDIVIDUAL + 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 + 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: @@ -8635,6 +8903,11 @@ components: 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. KycStatus: type: string enum: @@ -9503,6 +9776,16 @@ components: type: string description: Provider-specific token that can be used in place of the hosted URL — for example, to embed the provider's SDK directly in your application. Only returned for providers that support direct SDK integration. Whether to use the hosted URL or the embedded SDK is up to you; both flows result in the same `kycStatus` update on the customer. example: _act-sbx-jwt-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... + 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' InternalAccountType: title: Internal Account Type type: string diff --git a/mintlify/snippets/kyc/kyc-unregulated.mdx b/mintlify/snippets/kyc/kyc-unregulated.mdx index 3e4df465..68fdb506 100644 --- a/mintlify/snippets/kyc/kyc-unregulated.mdx +++ b/mintlify/snippets/kyc/kyc-unregulated.mdx @@ -69,6 +69,21 @@ The response always includes `kycUrl` for the hosted flow. For providers that su Call `POST /customers` with `customerType` and any pre-fill fields you have. The returned `id` is the customer's Grid ID; their `kycStatus` is `PENDING` until verification completes. + + Some regions (for example, the EU) require the customer's email and/or phone to be verified before KYC can begin. When this applies, the customer carries a `contactVerification` object listing **only the channels that are required** — for example `{ "email": "PENDING", "phone": "PENDING" }`, or just `{ "email": "PENDING" }` if a provider requires email alone. When the object is absent, no contact verification is required and you can skip this step. + + For each channel that's present, drive a send-then-confirm pair (the provider delivers a one-time code by email/SMS): + + - `POST /customers/{customerId}/verify-email`, then `POST /customers/{customerId}/verify-email/confirm` with `{ "code": "..." }` + - `POST /customers/{customerId}/verify-phone`, then `POST /customers/{customerId}/verify-phone/confirm` with `{ "code": "..." }` + + Re-POST the send endpoint to resend a code. Each channel moves `PENDING` → `VERIFIED`. (`verify-email`/`verify-phone` return `409` for a channel the provider doesn't require.) + + + Generating the KYC link before every present channel is `VERIFIED` returns `409`. + + + Call `POST /customers/{customerId}/kyc-link`. Each call returns a fresh single-use `kycUrl` and `expiresAt`; previously-issued links remain single-use but aren't invalidated. @@ -132,6 +147,10 @@ The shape of the flow depends on the customer type: } }' ``` + + + Where the customer's provider requires it (for example, EU customers), the customer carries a `contactVerification` object and their email and phone must be `VERIFIED` before you submit for verification. Drive each channel with the send-then-confirm pairs (`verify-email` / `verify-email/confirm` and `verify-phone` / `verify-phone/confirm`) described in the Hosted flow's "Verify email and phone" step. When `contactVerification` is absent, no contact verification is required. + diff --git a/openapi.yaml b/openapi.yaml index a73b3fd7..f5aff089 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -21,6 +21,8 @@ tags: description: Platform configuration endpoints for managing global settings. You can also configure these settings in the Grid dashboard. - name: Customers description: Customer management endpoints for creating and updating customer information + - 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. - name: KYC/KYB Verifications description: Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) verification, including managing beneficial owners and triggering verification for customers. - name: Documents @@ -843,6 +845,252 @@ paths: application/json: schema: $ref: '#/components/schemas/Error404' + '409': + description: The customer's payment provider requires contact verification and the customer's email and phone are not both `VERIFIED` yet. Complete contact verification (see `verify-email` and `verify-phone`) before generating a KYC link. + 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: + 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: @@ -8579,6 +8827,26 @@ components: - BUSINESS description: Whether the customer is an individual or a business entity example: INDIVIDUAL + 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 + 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: @@ -8635,6 +8903,11 @@ components: 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. KycStatus: type: string enum: @@ -9503,6 +9776,16 @@ components: type: string description: Provider-specific token that can be used in place of the hosted URL — for example, to embed the provider's SDK directly in your application. Only returned for providers that support direct SDK integration. Whether to use the hosted URL or the embedded SDK is up to you; both flows result in the same `kycStatus` update on the customer. example: _act-sbx-jwt-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... + 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' InternalAccountType: title: Internal Account Type type: string diff --git a/openapi/components/schemas/customers/ContactVerification.yaml b/openapi/components/schemas/customers/ContactVerification.yaml new file mode 100644 index 00000000..b388897e --- /dev/null +++ b/openapi/components/schemas/customers/ContactVerification.yaml @@ -0,0 +1,26 @@ +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: ./ContactVerificationStatus.yaml + description: >- + Verification status of the customer's email address. Present only when the + provider requires email verification. + phone: + $ref: ./ContactVerificationStatus.yaml + description: >- + Verification status of the customer's phone number. Present only when the + provider requires phone verification. diff --git a/openapi/components/schemas/customers/ContactVerificationConfirmRequest.yaml b/openapi/components/schemas/customers/ContactVerificationConfirmRequest.yaml new file mode 100644 index 00000000..e2bebe5b --- /dev/null +++ b/openapi/components/schemas/customers/ContactVerificationConfirmRequest.yaml @@ -0,0 +1,11 @@ +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' diff --git a/openapi/components/schemas/customers/ContactVerificationStatus.yaml b/openapi/components/schemas/customers/ContactVerificationStatus.yaml new file mode 100644 index 00000000..56475310 --- /dev/null +++ b/openapi/components/schemas/customers/ContactVerificationStatus.yaml @@ -0,0 +1,9 @@ +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 diff --git a/openapi/components/schemas/customers/Customer.yaml b/openapi/components/schemas/customers/Customer.yaml index 9bf15bdf..32fc6b52 100644 --- a/openapi/components/schemas/customers/Customer.yaml +++ b/openapi/components/schemas/customers/Customer.yaml @@ -59,3 +59,10 @@ properties: description: Whether the customer is marked as deleted example: false readOnly: true + contactVerification: + allOf: + - $ref: ./ContactVerification.yaml + readOnly: true + description: >- + Email and phone verification state. **Only present when the customer's + payment provider requires it** (e.g. EU customers); omitted otherwise. diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 7c509543..cc7f0e3c 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -18,6 +18,11 @@ tags: also configure these settings in the Grid dashboard. - name: Customers description: Customer management endpoints for creating and updating customer information + - 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. - name: KYC/KYB Verifications description: >- Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) @@ -131,6 +136,14 @@ paths: $ref: paths/customers/customers_{customerId}.yaml /customers/{customerId}/kyc-link: $ref: paths/customers/customers_{customerId}_kyc-link.yaml + /customers/{customerId}/verify-email: + $ref: paths/customers/customers_{customerId}_verify-email.yaml + /customers/{customerId}/verify-email/confirm: + $ref: paths/customers/customers_{customerId}_verify-email_confirm.yaml + /customers/{customerId}/verify-phone: + $ref: paths/customers/customers_{customerId}_verify-phone.yaml + /customers/{customerId}/verify-phone/confirm: + $ref: paths/customers/customers_{customerId}_verify-phone_confirm.yaml /customers/internal-accounts: $ref: paths/customers/customers_internal_accounts.yaml /platform/internal-accounts: diff --git a/openapi/paths/customers/customers_{customerId}_kyc-link.yaml b/openapi/paths/customers/customers_{customerId}_kyc-link.yaml index 566e3874..e077e5cc 100644 --- a/openapi/paths/customers/customers_{customerId}_kyc-link.yaml +++ b/openapi/paths/customers/customers_{customerId}_kyc-link.yaml @@ -59,6 +59,16 @@ post: application/json: schema: $ref: ../../components/schemas/errors/Error404.yaml + '409': + description: >- + The customer's payment provider requires contact verification and the + customer's email and phone are not both `VERIFIED` yet. Complete contact + verification (see `verify-email` and `verify-phone`) before generating a + KYC link. + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error409.yaml '500': description: Internal service error content: diff --git a/openapi/paths/customers/customers_{customerId}_verify-email.yaml b/openapi/paths/customers/customers_{customerId}_verify-email.yaml new file mode 100644 index 00000000..f6fdac76 --- /dev/null +++ b/openapi/paths/customers/customers_{customerId}_verify-email.yaml @@ -0,0 +1,56 @@ +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/errors/Error401.yaml + '404': + description: Customer not found + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error404.yaml + '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/errors/Error409.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/customers/customers_{customerId}_verify-email_confirm.yaml b/openapi/paths/customers/customers_{customerId}_verify-email_confirm.yaml new file mode 100644 index 00000000..aa5e4619 --- /dev/null +++ b/openapi/paths/customers/customers_{customerId}_verify-email_confirm.yaml @@ -0,0 +1,66 @@ +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/customers/ContactVerificationConfirmRequest.yaml + responses: + '200': + description: Email verified. + content: + application/json: + schema: + $ref: ../../components/schemas/customers/Customer.yaml + '400': + description: Invalid or expired code + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error401.yaml + '404': + description: Customer not found + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error404.yaml + '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/errors/Error409.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/customers/customers_{customerId}_verify-phone.yaml b/openapi/paths/customers/customers_{customerId}_verify-phone.yaml new file mode 100644 index 00000000..326823f4 --- /dev/null +++ b/openapi/paths/customers/customers_{customerId}_verify-phone.yaml @@ -0,0 +1,56 @@ +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/errors/Error401.yaml + '404': + description: Customer not found + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error404.yaml + '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/errors/Error409.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml diff --git a/openapi/paths/customers/customers_{customerId}_verify-phone_confirm.yaml b/openapi/paths/customers/customers_{customerId}_verify-phone_confirm.yaml new file mode 100644 index 00000000..73eb3982 --- /dev/null +++ b/openapi/paths/customers/customers_{customerId}_verify-phone_confirm.yaml @@ -0,0 +1,66 @@ +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/customers/ContactVerificationConfirmRequest.yaml + responses: + '200': + description: Phone verified. + content: + application/json: + schema: + $ref: ../../components/schemas/customers/Customer.yaml + '400': + description: Invalid or expired code + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error400.yaml + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error401.yaml + '404': + description: Customer not found + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error404.yaml + '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/errors/Error409.yaml + '500': + description: Internal service error + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error500.yaml