diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index d93a10d11..9f9e30be1 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -368,6 +368,8 @@ paths: fullName: Jane Smith birthDate: '1990-01-15' nationality: US + email: jane.smith@example.com + phoneNumber: '+14155551234' individualCustomerInferred: summary: Create an individual customer with inferred currencies value: @@ -377,6 +379,7 @@ paths: fullName: Carlos García birthDate: '1988-05-22' nationality: MX + phoneNumber: '+525512345678' businessCustomer: summary: Create a business customer value: @@ -386,6 +389,8 @@ paths: currencies: - USD - USDC + email: finance@acme.com + phoneNumber: '+14155559876' businessInfo: legalName: Acme Corporation doingBusinessAs: Acme @@ -621,11 +626,13 @@ paths: description: | Update a customer's metadata by their system-generated ID. - Most customer updates complete synchronously and return `200` with the updated customer. If the request changes `email` for a customer that has one or more tied Embedded Wallet internal accounts with `EMAIL_OTP` credentials, the email change uses the two-step signed-retry flow so the customer's wallet session authorizes the authentication credential update. On the signed retry, Grid updates the customer email and every tied `EMAIL_OTP` credential across all tied Embedded Wallets as one logical operation. If any tied credential cannot be updated, the customer email is not changed. + Most customer updates complete synchronously and return `200` with the updated customer. If the request changes `email` for a customer that has one or more tied Embedded Wallet internal accounts with `EMAIL_OTP` credentials, or changes `phoneNumber` for a customer that has one or more tied Embedded Wallet internal accounts with `SMS_OTP` credentials, the contact update uses the two-step signed-retry flow so the customer's wallet session authorizes the authentication credential update. On the signed retry, Grid updates the customer contact field and every tied matching OTP credential across all tied Embedded Wallets as one logical operation. If any tied credential cannot be updated, the customer contact field is not changed. - For an Embedded Wallet email update: + Update `email` and `phoneNumber` in separate PATCH calls. A request that includes both fields is rejected. - 1. Call `PATCH /customers/{customerId}` with the full update body and no signature headers. Grid returns `202` with `payloadToSign`, `requestId`, and `expiresAt`. The pending challenge binds the submitted update fields and the set of tied Embedded Wallet email OTP credentials that must be updated. + For an Embedded Wallet email or SMS auth phone update: + + 1. Call `PATCH /customers/{customerId}` with the full update body and no signature headers. Grid returns `202` with `payloadToSign`, `requestId`, and `expiresAt`. The pending challenge binds the submitted update fields and the set of tied Embedded Wallet OTP credentials that must be updated. 2. Use the session API keypair of a verified authentication credential on one of the customer's tied Embedded Wallets to build an API-key stamp over `payloadToSign`, then retry the same request with that full stamp as the `Grid-Wallet-Signature` header and the `requestId` echoed back as the `Request-Id` header. The retry body must carry the same update fields submitted in step 1. The signed retry returns `200` with the updated customer. operationId: updateCustomerById @@ -637,14 +644,14 @@ paths: - name: Grid-Wallet-Signature in: header required: false - description: Full API-key stamp built over the prior `payloadToSign` with the session API keypair of a verified authentication credential on one of the customer's tied Embedded Wallets. Required on the signed retry for Embedded Wallet email updates; ignored on the initial call and on customer updates that complete synchronously. + description: Full API-key stamp built over the prior `payloadToSign` with the session API keypair of a verified authentication credential on one of the customer's tied Embedded Wallets. Required on the signed retry for Embedded Wallet email or SMS auth phone updates; ignored on the initial call and on customer updates that complete synchronously. schema: type: string example: eyJwdWJsaWNLZXkiOiIwMmExYjIuLi4iLCJzY2hlbWUiOiJTSUdOQVRVUkVfU0NIRU1FX1RLX0FQSV9QMjU2Iiwic2lnbmF0dXJlIjoiMzA0NTAyMjEwMC4uLiJ9 - name: Request-Id in: header required: false - description: The `requestId` returned in a prior `202` response, echoed back on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry for Embedded Wallet email updates; must be paired with `Grid-Wallet-Signature`. + description: The `requestId` returned in a prior `202` response, echoed back on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry for Embedded Wallet email or SMS auth phone updates; must be paired with `Grid-Wallet-Signature`. schema: type: string example: Request:019542f5-b3e7-1d02-0000-000000000010 @@ -693,15 +700,26 @@ paths: value: customerType: INDIVIDUAL email: john.smith@example.com + embeddedWalletPhoneUpdate: + summary: Embedded Wallet SMS auth phone update request (both steps) + value: + customerType: INDIVIDUAL + phoneNumber: '+14155559876' + combinedContactUpdateRejected: + summary: Combined email and phone update request (rejected) + value: + customerType: INDIVIDUAL + email: john.smith@example.com + phoneNumber: '+14155559876' responses: '200': - description: Customer updated successfully. For Embedded Wallet email updates, this is returned only on the signed retry after the customer email and all tied email OTP credentials have been updated. + description: Customer updated successfully. For Embedded Wallet email or SMS auth phone updates, this is returned only on the signed retry after the customer contact field and all tied matching OTP credentials have been updated. content: application/json: schema: $ref: '#/components/schemas/CustomerOneOf' '202': - description: Challenge issued for an Embedded Wallet email update. The response contains `payloadToSign` plus a `requestId`. Build an API-key stamp over `payloadToSign` with the session API keypair from a verified authentication credential on one of the customer's tied Embedded Wallets, then retry the same request with `Grid-Wallet-Signature` and `Request-Id`. + description: Challenge issued for an Embedded Wallet email or SMS auth phone update. The response contains `payloadToSign` plus a `requestId`. Build an API-key stamp over `payloadToSign` with the session API keypair from a verified authentication credential on one of the customer's tied Embedded Wallets, then retry the same request with `Grid-Wallet-Signature` and `Request-Id`. content: application/json: schema: @@ -713,6 +731,12 @@ paths: payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"userEmail":"john.smith@example.com","userId":"user_2m9F..."},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_UPDATE_USER_EMAIL"}' requestId: Request:019542f5-b3e7-1d02-0000-000000000010 expiresAt: '2026-04-08T15:35:00Z' + embeddedWalletPhoneUpdate: + summary: Embedded Wallet customer SMS auth phone update challenge + value: + payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"userId":"user_2m9F...","userPhoneNumber":"+14155559876"},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_UPDATE_USER_PHONE_NUMBER"}' + requestId: Request:019542f5-b3e7-1d02-0000-000000000011 + expiresAt: '2026-04-08T15:35:00Z' '400': description: Bad request content: @@ -720,7 +744,7 @@ paths: schema: $ref: '#/components/schemas/Error400' '401': - description: Unauthorized. Also returned for Embedded Wallet email update retries when the provided `Grid-Wallet-Signature` is missing, malformed, or does not match the pending customer update challenge, when the `Request-Id` does not match an unexpired pending challenge, or when the retry body does not match the update fields bound into `payloadToSign` on the initial call. + description: Unauthorized. Also returned for Embedded Wallet email or SMS auth phone update retries when the provided `Grid-Wallet-Signature` is missing, malformed, or does not match the pending customer update challenge, when the `Request-Id` does not match an unexpired pending challenge, or when the retry body does not match the update fields bound into `payloadToSign` on the initial call. content: application/json: schema: @@ -732,13 +756,13 @@ paths: schema: $ref: '#/components/schemas/Error404' '409': - description: Conflict. Returned when the supplied email address is already associated with an `EMAIL_OTP` credential on this or another internal account, or when the tied Embedded Wallet email OTP credential set changed between the initial `202` challenge and the signed retry. + description: Conflict. Returned when the supplied email address is already associated with an `EMAIL_OTP` credential, or the supplied phone number is already associated with an `SMS_OTP` credential, on this or another internal account, or when the tied Embedded Wallet OTP credential set changed between the initial `202` challenge and the signed retry. content: application/json: schema: $ref: '#/components/schemas/Error409' '424': - description: Failed dependency. Returned when Grid cannot update one or more tied Embedded Wallet email OTP credentials. The customer email is not changed unless all tied credentials are updated successfully. + description: Failed dependency. Returned when Grid cannot update one or more tied Embedded Wallet OTP credentials. The customer contact field is not changed unless all tied credentials are updated successfully. content: application/json: schema: @@ -9367,6 +9391,11 @@ components: 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. @@ -9911,6 +9940,11 @@ components: 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: Optional UMA address identifier. If not provided during customer creation, one will be generated by the system. If provided during customer update, the UMA address will be updated to the provided value. This is an optional identifier to route payments to the customer. This is an optional identifier to route payments to the customer. @@ -10124,7 +10158,7 @@ components: additionalProperties: true CustomerUpdateRequest: title: Customer Update Request - description: Request body for `PATCH /customers/{customerId}`. When `email` changes for a customer with tied Embedded Wallet internal accounts, Grid updates the customer email and every tied `EMAIL_OTP` credential across all tied Embedded Wallets through the endpoint's signed-retry flow. + description: Request body for `PATCH /customers/{customerId}`. When `email` changes for a customer with tied Embedded Wallet internal accounts, Grid updates the customer email and every tied `EMAIL_OTP` credential through the endpoint's signed-retry flow. When `phoneNumber` changes for a customer with tied Embedded Wallet internal accounts, Grid updates the customer phone number and every tied `SMS_OTP` credential through the same signed-retry flow. Update `email` and `phoneNumber` in separate PATCH calls. type: object required: - customerType @@ -10145,6 +10179,11 @@ components: format: email description: Email address for the customer. For customers with tied Embedded Wallet internal accounts, changing this value also updates every tied `EMAIL_OTP` credential across all tied Embedded Wallets. 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. For customers with tied Embedded Wallet internal accounts, changing this value also updates every tied `SMS_OTP` credential across all tied Embedded Wallets. Send phone number and email updates as separate PATCH calls. + example: '+14155551234' umaAddress: type: string description: Optional UMA address identifier. If provided, the customer's UMA address will be updated. This is an optional identifier to route payments to the customer. diff --git a/openapi.yaml b/openapi.yaml index d93a10d11..9f9e30be1 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -368,6 +368,8 @@ paths: fullName: Jane Smith birthDate: '1990-01-15' nationality: US + email: jane.smith@example.com + phoneNumber: '+14155551234' individualCustomerInferred: summary: Create an individual customer with inferred currencies value: @@ -377,6 +379,7 @@ paths: fullName: Carlos García birthDate: '1988-05-22' nationality: MX + phoneNumber: '+525512345678' businessCustomer: summary: Create a business customer value: @@ -386,6 +389,8 @@ paths: currencies: - USD - USDC + email: finance@acme.com + phoneNumber: '+14155559876' businessInfo: legalName: Acme Corporation doingBusinessAs: Acme @@ -621,11 +626,13 @@ paths: description: | Update a customer's metadata by their system-generated ID. - Most customer updates complete synchronously and return `200` with the updated customer. If the request changes `email` for a customer that has one or more tied Embedded Wallet internal accounts with `EMAIL_OTP` credentials, the email change uses the two-step signed-retry flow so the customer's wallet session authorizes the authentication credential update. On the signed retry, Grid updates the customer email and every tied `EMAIL_OTP` credential across all tied Embedded Wallets as one logical operation. If any tied credential cannot be updated, the customer email is not changed. + Most customer updates complete synchronously and return `200` with the updated customer. If the request changes `email` for a customer that has one or more tied Embedded Wallet internal accounts with `EMAIL_OTP` credentials, or changes `phoneNumber` for a customer that has one or more tied Embedded Wallet internal accounts with `SMS_OTP` credentials, the contact update uses the two-step signed-retry flow so the customer's wallet session authorizes the authentication credential update. On the signed retry, Grid updates the customer contact field and every tied matching OTP credential across all tied Embedded Wallets as one logical operation. If any tied credential cannot be updated, the customer contact field is not changed. - For an Embedded Wallet email update: + Update `email` and `phoneNumber` in separate PATCH calls. A request that includes both fields is rejected. - 1. Call `PATCH /customers/{customerId}` with the full update body and no signature headers. Grid returns `202` with `payloadToSign`, `requestId`, and `expiresAt`. The pending challenge binds the submitted update fields and the set of tied Embedded Wallet email OTP credentials that must be updated. + For an Embedded Wallet email or SMS auth phone update: + + 1. Call `PATCH /customers/{customerId}` with the full update body and no signature headers. Grid returns `202` with `payloadToSign`, `requestId`, and `expiresAt`. The pending challenge binds the submitted update fields and the set of tied Embedded Wallet OTP credentials that must be updated. 2. Use the session API keypair of a verified authentication credential on one of the customer's tied Embedded Wallets to build an API-key stamp over `payloadToSign`, then retry the same request with that full stamp as the `Grid-Wallet-Signature` header and the `requestId` echoed back as the `Request-Id` header. The retry body must carry the same update fields submitted in step 1. The signed retry returns `200` with the updated customer. operationId: updateCustomerById @@ -637,14 +644,14 @@ paths: - name: Grid-Wallet-Signature in: header required: false - description: Full API-key stamp built over the prior `payloadToSign` with the session API keypair of a verified authentication credential on one of the customer's tied Embedded Wallets. Required on the signed retry for Embedded Wallet email updates; ignored on the initial call and on customer updates that complete synchronously. + description: Full API-key stamp built over the prior `payloadToSign` with the session API keypair of a verified authentication credential on one of the customer's tied Embedded Wallets. Required on the signed retry for Embedded Wallet email or SMS auth phone updates; ignored on the initial call and on customer updates that complete synchronously. schema: type: string example: eyJwdWJsaWNLZXkiOiIwMmExYjIuLi4iLCJzY2hlbWUiOiJTSUdOQVRVUkVfU0NIRU1FX1RLX0FQSV9QMjU2Iiwic2lnbmF0dXJlIjoiMzA0NTAyMjEwMC4uLiJ9 - name: Request-Id in: header required: false - description: The `requestId` returned in a prior `202` response, echoed back on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry for Embedded Wallet email updates; must be paired with `Grid-Wallet-Signature`. + description: The `requestId` returned in a prior `202` response, echoed back on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry for Embedded Wallet email or SMS auth phone updates; must be paired with `Grid-Wallet-Signature`. schema: type: string example: Request:019542f5-b3e7-1d02-0000-000000000010 @@ -693,15 +700,26 @@ paths: value: customerType: INDIVIDUAL email: john.smith@example.com + embeddedWalletPhoneUpdate: + summary: Embedded Wallet SMS auth phone update request (both steps) + value: + customerType: INDIVIDUAL + phoneNumber: '+14155559876' + combinedContactUpdateRejected: + summary: Combined email and phone update request (rejected) + value: + customerType: INDIVIDUAL + email: john.smith@example.com + phoneNumber: '+14155559876' responses: '200': - description: Customer updated successfully. For Embedded Wallet email updates, this is returned only on the signed retry after the customer email and all tied email OTP credentials have been updated. + description: Customer updated successfully. For Embedded Wallet email or SMS auth phone updates, this is returned only on the signed retry after the customer contact field and all tied matching OTP credentials have been updated. content: application/json: schema: $ref: '#/components/schemas/CustomerOneOf' '202': - description: Challenge issued for an Embedded Wallet email update. The response contains `payloadToSign` plus a `requestId`. Build an API-key stamp over `payloadToSign` with the session API keypair from a verified authentication credential on one of the customer's tied Embedded Wallets, then retry the same request with `Grid-Wallet-Signature` and `Request-Id`. + description: Challenge issued for an Embedded Wallet email or SMS auth phone update. The response contains `payloadToSign` plus a `requestId`. Build an API-key stamp over `payloadToSign` with the session API keypair from a verified authentication credential on one of the customer's tied Embedded Wallets, then retry the same request with `Grid-Wallet-Signature` and `Request-Id`. content: application/json: schema: @@ -713,6 +731,12 @@ paths: payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"userEmail":"john.smith@example.com","userId":"user_2m9F..."},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_UPDATE_USER_EMAIL"}' requestId: Request:019542f5-b3e7-1d02-0000-000000000010 expiresAt: '2026-04-08T15:35:00Z' + embeddedWalletPhoneUpdate: + summary: Embedded Wallet customer SMS auth phone update challenge + value: + payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"userId":"user_2m9F...","userPhoneNumber":"+14155559876"},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_UPDATE_USER_PHONE_NUMBER"}' + requestId: Request:019542f5-b3e7-1d02-0000-000000000011 + expiresAt: '2026-04-08T15:35:00Z' '400': description: Bad request content: @@ -720,7 +744,7 @@ paths: schema: $ref: '#/components/schemas/Error400' '401': - description: Unauthorized. Also returned for Embedded Wallet email update retries when the provided `Grid-Wallet-Signature` is missing, malformed, or does not match the pending customer update challenge, when the `Request-Id` does not match an unexpired pending challenge, or when the retry body does not match the update fields bound into `payloadToSign` on the initial call. + description: Unauthorized. Also returned for Embedded Wallet email or SMS auth phone update retries when the provided `Grid-Wallet-Signature` is missing, malformed, or does not match the pending customer update challenge, when the `Request-Id` does not match an unexpired pending challenge, or when the retry body does not match the update fields bound into `payloadToSign` on the initial call. content: application/json: schema: @@ -732,13 +756,13 @@ paths: schema: $ref: '#/components/schemas/Error404' '409': - description: Conflict. Returned when the supplied email address is already associated with an `EMAIL_OTP` credential on this or another internal account, or when the tied Embedded Wallet email OTP credential set changed between the initial `202` challenge and the signed retry. + description: Conflict. Returned when the supplied email address is already associated with an `EMAIL_OTP` credential, or the supplied phone number is already associated with an `SMS_OTP` credential, on this or another internal account, or when the tied Embedded Wallet OTP credential set changed between the initial `202` challenge and the signed retry. content: application/json: schema: $ref: '#/components/schemas/Error409' '424': - description: Failed dependency. Returned when Grid cannot update one or more tied Embedded Wallet email OTP credentials. The customer email is not changed unless all tied credentials are updated successfully. + description: Failed dependency. Returned when Grid cannot update one or more tied Embedded Wallet OTP credentials. The customer contact field is not changed unless all tied credentials are updated successfully. content: application/json: schema: @@ -9367,6 +9391,11 @@ components: 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. @@ -9911,6 +9940,11 @@ components: 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: Optional UMA address identifier. If not provided during customer creation, one will be generated by the system. If provided during customer update, the UMA address will be updated to the provided value. This is an optional identifier to route payments to the customer. This is an optional identifier to route payments to the customer. @@ -10124,7 +10158,7 @@ components: additionalProperties: true CustomerUpdateRequest: title: Customer Update Request - description: Request body for `PATCH /customers/{customerId}`. When `email` changes for a customer with tied Embedded Wallet internal accounts, Grid updates the customer email and every tied `EMAIL_OTP` credential across all tied Embedded Wallets through the endpoint's signed-retry flow. + description: Request body for `PATCH /customers/{customerId}`. When `email` changes for a customer with tied Embedded Wallet internal accounts, Grid updates the customer email and every tied `EMAIL_OTP` credential through the endpoint's signed-retry flow. When `phoneNumber` changes for a customer with tied Embedded Wallet internal accounts, Grid updates the customer phone number and every tied `SMS_OTP` credential through the same signed-retry flow. Update `email` and `phoneNumber` in separate PATCH calls. type: object required: - customerType @@ -10145,6 +10179,11 @@ components: format: email description: Email address for the customer. For customers with tied Embedded Wallet internal accounts, changing this value also updates every tied `EMAIL_OTP` credential across all tied Embedded Wallets. 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. For customers with tied Embedded Wallet internal accounts, changing this value also updates every tied `SMS_OTP` credential across all tied Embedded Wallets. Send phone number and email updates as separate PATCH calls. + example: '+14155551234' umaAddress: type: string description: Optional UMA address identifier. If provided, the customer's UMA address will be updated. This is an optional identifier to route payments to the customer. diff --git a/openapi/components/schemas/customers/Customer.yaml b/openapi/components/schemas/customers/Customer.yaml index 32fc6b525..1e11a5c7c 100644 --- a/openapi/components/schemas/customers/Customer.yaml +++ b/openapi/components/schemas/customers/Customer.yaml @@ -36,6 +36,12 @@ properties: 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: >- diff --git a/openapi/components/schemas/customers/CustomerCreateRequest.yaml b/openapi/components/schemas/customers/CustomerCreateRequest.yaml index b43e36d54..b2bd01347 100644 --- a/openapi/components/schemas/customers/CustomerCreateRequest.yaml +++ b/openapi/components/schemas/customers/CustomerCreateRequest.yaml @@ -36,6 +36,12 @@ properties: 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: >- diff --git a/openapi/components/schemas/customers/CustomerUpdateRequest.yaml b/openapi/components/schemas/customers/CustomerUpdateRequest.yaml index 15cccec5c..7f3c56a58 100644 --- a/openapi/components/schemas/customers/CustomerUpdateRequest.yaml +++ b/openapi/components/schemas/customers/CustomerUpdateRequest.yaml @@ -2,8 +2,11 @@ title: Customer Update Request description: >- Request body for `PATCH /customers/{customerId}`. When `email` changes for a customer with tied Embedded Wallet internal accounts, Grid updates the - customer email and every tied `EMAIL_OTP` credential across all tied Embedded - Wallets through the endpoint's signed-retry flow. + customer email and every tied `EMAIL_OTP` credential through the endpoint's + signed-retry flow. When `phoneNumber` changes for a customer with tied + Embedded Wallet internal accounts, Grid updates the customer phone number and + every tied `SMS_OTP` credential through the same signed-retry flow. Update + `email` and `phoneNumber` in separate PATCH calls. type: object required: - customerType @@ -31,6 +34,15 @@ properties: internal accounts, changing this value also updates every tied `EMAIL_OTP` credential across all tied Embedded Wallets. 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. For customers with + tied Embedded Wallet internal accounts, changing this value also updates + every tied `SMS_OTP` credential across all tied Embedded Wallets. Send + phone number and email updates as separate PATCH calls. + example: '+14155551234' umaAddress: type: string description: >- diff --git a/openapi/paths/customers/customers.yaml b/openapi/paths/customers/customers.yaml index c0eddd2c3..a87e24512 100644 --- a/openapi/paths/customers/customers.yaml +++ b/openapi/paths/customers/customers.yaml @@ -27,6 +27,8 @@ post: fullName: Jane Smith birthDate: '1990-01-15' nationality: US + email: jane.smith@example.com + phoneNumber: '+14155551234' individualCustomerInferred: summary: Create an individual customer with inferred currencies value: @@ -36,6 +38,7 @@ post: fullName: Carlos García birthDate: '1988-05-22' nationality: MX + phoneNumber: '+525512345678' businessCustomer: summary: Create a business customer value: @@ -45,6 +48,8 @@ post: currencies: - USD - USDC + email: finance@acme.com + phoneNumber: '+14155559876' businessInfo: legalName: Acme Corporation doingBusinessAs: Acme diff --git a/openapi/paths/customers/customers_{customerId}.yaml b/openapi/paths/customers/customers_{customerId}.yaml index 1dd118a44..f5c82ac91 100644 --- a/openapi/paths/customers/customers_{customerId}.yaml +++ b/openapi/paths/customers/customers_{customerId}.yaml @@ -47,22 +47,27 @@ patch: Most customer updates complete synchronously and return `200` with the updated customer. If the request changes `email` for a customer that has one or more tied Embedded Wallet internal accounts with `EMAIL_OTP` - credentials, the email change uses the two-step signed-retry flow so the - customer's wallet session authorizes the authentication credential update. - On the signed retry, Grid updates the customer email and every tied - `EMAIL_OTP` credential across all tied Embedded Wallets as one logical - operation. If any tied credential cannot be updated, the customer email is - not changed. + credentials, or changes `phoneNumber` for a customer that has one or more + tied Embedded Wallet internal accounts with `SMS_OTP` credentials, the + contact update uses the two-step signed-retry flow so the customer's wallet + session authorizes the authentication credential update. On the signed + retry, Grid updates the customer contact field and every tied matching OTP + credential across all tied Embedded Wallets as one logical operation. If + any tied credential cannot be updated, the customer contact field is not + changed. - For an Embedded Wallet email update: + Update `email` and `phoneNumber` in separate PATCH calls. A request that + includes both fields is rejected. + + + For an Embedded Wallet email or SMS auth phone update: 1. Call `PATCH /customers/{customerId}` with the full update body and no signature headers. Grid returns `202` with `payloadToSign`, `requestId`, and `expiresAt`. The pending challenge binds the submitted update fields - and the set of tied Embedded Wallet email OTP credentials that must be - updated. + and the set of tied Embedded Wallet OTP credentials that must be updated. 2. Use the session API keypair of a verified authentication credential on @@ -85,8 +90,8 @@ patch: Full API-key stamp built over the prior `payloadToSign` with the session API keypair of a verified authentication credential on one of the customer's tied Embedded Wallets. Required on the signed retry for - Embedded Wallet email updates; ignored on the initial call and on - customer updates that complete synchronously. + Embedded Wallet email or SMS auth phone updates; ignored on the initial + call and on customer updates that complete synchronously. schema: type: string example: eyJwdWJsaWNLZXkiOiIwMmExYjIuLi4iLCJzY2hlbWUiOiJTSUdOQVRVUkVfU0NIRU1FX1RLX0FQSV9QMjU2Iiwic2lnbmF0dXJlIjoiMzA0NTAyMjEwMC4uLiJ9 @@ -96,8 +101,8 @@ patch: description: >- The `requestId` returned in a prior `202` response, echoed back on the signed retry so the server can correlate it with the issued challenge. - Required on the signed retry for Embedded Wallet email updates; must - be paired with `Grid-Wallet-Signature`. + Required on the signed retry for Embedded Wallet email or SMS auth phone + updates; must be paired with `Grid-Wallet-Signature`. schema: type: string example: Request:019542f5-b3e7-1d02-0000-000000000010 @@ -146,24 +151,36 @@ patch: value: customerType: INDIVIDUAL email: john.smith@example.com + embeddedWalletPhoneUpdate: + summary: Embedded Wallet SMS auth phone update request (both steps) + value: + customerType: INDIVIDUAL + phoneNumber: '+14155559876' + combinedContactUpdateRejected: + summary: Combined email and phone update request (rejected) + value: + customerType: INDIVIDUAL + email: john.smith@example.com + phoneNumber: '+14155559876' responses: '200': description: >- - Customer updated successfully. For Embedded Wallet email updates, this - is returned only on the signed retry after the customer email and all - tied email OTP credentials have been updated. + Customer updated successfully. For Embedded Wallet email or SMS auth + phone updates, this is returned only on the signed retry after the + customer contact field and all tied matching OTP credentials have been + updated. content: application/json: schema: $ref: ../../components/schemas/customers/CustomerOneOf.yaml '202': description: >- - Challenge issued for an Embedded Wallet email update. The response - contains `payloadToSign` plus a `requestId`. Build an API-key stamp - over `payloadToSign` with the session API keypair from a verified - authentication credential on one of the customer's tied Embedded - Wallets, then retry the same request with `Grid-Wallet-Signature` and - `Request-Id`. + Challenge issued for an Embedded Wallet email or SMS auth phone update. + The response contains `payloadToSign` plus a `requestId`. Build an + API-key stamp over `payloadToSign` with the session API keypair from a + verified authentication credential on one of the customer's tied + Embedded Wallets, then retry the same request with + `Grid-Wallet-Signature` and `Request-Id`. content: application/json: schema: @@ -175,6 +192,12 @@ patch: payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"userEmail":"john.smith@example.com","userId":"user_2m9F..."},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_UPDATE_USER_EMAIL"}' requestId: Request:019542f5-b3e7-1d02-0000-000000000010 expiresAt: '2026-04-08T15:35:00Z' + embeddedWalletPhoneUpdate: + summary: Embedded Wallet customer SMS auth phone update challenge + value: + payloadToSign: '{"organizationId":"org_2m9F...","parameters":{"userId":"user_2m9F...","userPhoneNumber":"+14155559876"},"timestampMs":"1775681700000","type":"ACTIVITY_TYPE_UPDATE_USER_PHONE_NUMBER"}' + requestId: Request:019542f5-b3e7-1d02-0000-000000000011 + expiresAt: '2026-04-08T15:35:00Z' '400': description: Bad request content: @@ -183,12 +206,12 @@ patch: $ref: ../../components/schemas/errors/Error400.yaml '401': description: >- - Unauthorized. Also returned for Embedded Wallet email update retries - when the provided `Grid-Wallet-Signature` is missing, malformed, or - does not match the pending customer update challenge, when the - `Request-Id` does not match an unexpired pending challenge, or when the - retry body does not match the update fields bound into `payloadToSign` - on the initial call. + Unauthorized. Also returned for Embedded Wallet email or SMS auth phone + update retries when the provided `Grid-Wallet-Signature` is missing, + malformed, or does not match the pending customer update challenge, + when the `Request-Id` does not match an unexpired pending challenge, or + when the retry body does not match the update fields bound into + `payloadToSign` on the initial call. content: application/json: schema: @@ -202,9 +225,11 @@ patch: '409': description: >- Conflict. Returned when the supplied email address is already - associated with an `EMAIL_OTP` credential on this or another internal - account, or when the tied Embedded Wallet email OTP credential set - changed between the initial `202` challenge and the signed retry. + associated with an `EMAIL_OTP` credential, or the supplied phone + number is already associated with an `SMS_OTP` credential, on this or + another internal account, or when the tied Embedded Wallet OTP + credential set changed between the initial `202` challenge and the + signed retry. content: application/json: schema: @@ -212,7 +237,7 @@ patch: '424': description: >- Failed dependency. Returned when Grid cannot update one or more tied - Embedded Wallet email OTP credentials. The customer email is not + Embedded Wallet OTP credentials. The customer contact field is not changed unless all tied credentials are updated successfully. content: application/json: