### Example theme usage

Source: https://docs.spherepay.co/widget/theming

Shows a complete example of creating a theme object and passing it to the RampWidget constructor. Uses a zinc color, no border radius, and a custom logo URL.

```javascript
const theme = {
  color: 'zinc',
  radius: 'none',
  components: {
    logo: 'https://example.com/logo.png',
  },
}

new RampWidget({
  containerId: 'container',
  applicationId: 'YOUR_APPLICATION_ID',
  theme,
})
```

--------------------------------

### Setup steps: container, script import, and initializer

Source: https://docs.spherepay.co/widget/setup

These three blocks are the sequential steps of the setup workflow: add a container element, import the hosted script, and implement the initializer function. The script tag's onload attribute calls initSphereRamp(), which creates a new RampWidget instance with the container ID and Merchant Application ID.

```html
<div id="container"></div>
```

```html
<script
  type="module"
  crossorigin
  src="https://spherepay.co/packages/sphere-ramp/index.js"
  onload="initSphereRamp()"
></script>
```

```javascript
function initSphereRamp() {
  new RampWidget({
    containerId: 'container',
    applicationId: 'YOUR_APPLICATION_ID',
  })
}
```

--------------------------------

### Customer verification profile response

Source: https://docs.spherepay.co/concepts/onboarding/individual-kyc

Example response from GET /v2/customer/{id} showing an approved verification profile with completed criteria. The 'required' array is empty and 'status' is 'approved', indicating full onboarding.

```json
{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "approved",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number",
          "identity_document",
          "liveness_report_document"
        ],
        "pending": [],
        "required": [],
        "errors": []
      }
    }
  ],
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "type": "individual"
}
```

--------------------------------

### OpenAPI GET /v2/transfer

Source: https://docs.spherepay.co/api-reference/transfer/get

OpenAPI specification for the GET /v2/transfer endpoint. Lists all transfers with pagination, filtering by customer, status, and type, and sorting. Includes response schemas and error examples.

```yaml
openapi: 3.0.0
info:
  contact: {}
  description: The Sphere REST API for payments, transfers, and accounts.
  title: Sphere API
  version: '2'
servers:
  - description: Production
    url: https://api.spherepay.co
security:
  - bearer: []
tags: []
paths:
  /v2/transfer:
    get:
      summary: List Transfers
      description: List all transfers
      operationId: getV2Transfer
      parameters:
        - description: 'Page number of the list (default: 1)'
          in: query
          name: page
          required: true
          schema:
            default: '1'
            example: 1
            type: string
        - description: 'Number of items per page (default: 10)'
          in: query
          name: limit
          required: true
          schema:
            default: '10'
            example: 10
            type: string
        - description: Query by Customer ID.
          in: query
          name: customer
          required: false
          schema:
            example: customer_123abc...
            type: string
        - description: >-
            Query by Payout status. See [Transfer
            Lifecycle](/concepts/transfers/lifecycle) for status definitions.
          in: query
          name: status
          required: false
          schema:
            enum:
              - pendingFunding
              - pendingReview
              - fundsReceived
              - processing
              - succeeded
              - undeliverable
              - returned
              - pendingRefundInformation
              - failed
              - canceled
              - refunded
              - unexpectedError
              - failedPrecondition
              - expired
              - unfunded
            example: succeeded
            type: string
          x-enumNames:
            - PENDING_FUNDING
            - PENDING_REVIEW
            - FUNDS_RECEIVED
            - PROCESSING
            - SUCCEEDED
            - UNDELIVERABLE
            - RETURNED
            - PENDING_REFUND_INFO
            - FAILED
            - CANCELED
            - REFUNDED
            - UNEXPECTED_ERROR
            - FAILED_PRECONDITION
            - EXPIRED
            - UNFUNDED
        - description: Query by Payout type.
          in: query
          name: type
          required: false
          schema:
            enum:
              - offRamp
              - onChain
              - onRamp
              - microdeposit
              - unmatchedDeposit
              - fiatToFiat
            example: onRamp
            type: string
          x-enumNames:
            - OffRamp
            - OnChain
            - OnRamp
            - Microdeposit
            - UnmatchedDeposit
            - FiatToFiat
        - description: >-
            Comma-separated sort fields. Prefix with "-" for descending, "+" (or
            no prefix) for ascending. Allowed fields: created, updated, status,
            type, amount. Example: "type,-created".
          in: query
          name: sort
          required: true
          schema:
            default: '-created'
            example: '-created'
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTransfersResponseDto'
          description: ''
        '400':
          content:
            application/json:
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Invalid request parameters
                    status: 400
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Resource not found
                    status: 404
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Not Found
        '422':
          content:
            application/json:
              examples:

```

--------------------------------

### Create a wallet with POST /v2/wallet

Source: https://docs.spherepay.co/get-started/first-api-call

Creates a wallet for a customer. The request requires a customer ID, an address, a network, and a currency. The response includes a system-generated wallet ID and status.

```bash
curl -X POST https://api.spherepay.co/v2/wallet \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "address": "0xAbC1234567890dEfAB1234567890DEFaB123456",
    "network": "ethereum",
    "currency": "usdc"
  }'
```

```json
{
    "id": "wallet_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "customerId": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "address": "0xAbC1234567890dEfAB1234567890DEFaB123456",
    "network": "ethereum",
    "currency": "usdc",
    "status": "active",
    "createdAt": "2026-03-03T21:35:00.000Z",
    "updatedAt": "2026-03-03T21:35:00.000Z"
}
```

--------------------------------

### OpenAPI Specification for GET /v2/bank-account/{id}

Source: https://docs.spherepay.co/api-reference/bank-account/get-id

OpenAPI 3.0.0 specification for the GET /v2/bank-account/{id} endpoint. It defines the path parameter 'id' (required, example 'bankAccount_ce745ef7f3df4b9a8bff1301ce24b045') and the 200 response schema with oneOf for USD account details (ACH/Wire or SWIFT).

```yaml
openapi: 3.0.0
info:
  contact: {}
  description: The Sphere REST API for payments, transfers, and accounts.
  title: Sphere API
  version: '2'
servers:
  - description: Production
    url: https://api.spherepay.co
security:
  - bearer: []
tags: []
paths:
  /v2/bank-account/{id}:
    get:
      summary: Get a Bank Account
      description: Get information about a bank account by its ID
      operationId: getV2BankAccountById
      parameters:
        - description: The bank account ID
          in: path
          name: id
          required: true
          schema:
            example: bankAccount_ce745ef7f3df4b9a8bff1301ce24b045
            minLength: 1
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                oneOf:
                  - properties:
                      accountDetails:
                        description: >-
                          USD account details. For ACH/Wire: accountNumber,
                          routingNumber, accountType. For SWIFT: accountNumber
                          (masked), bic.
                        oneOf:
                          - properties:
                              accountNumber:
                                description: >-
                                  The bank account number for the US bank
                                  account (masked, last 4 characters visible).
                                  Present when currency is usd.
                                example: '****7890'
                                type: string
                              accountType:
                                description: >-
                                  The type of US bank account. Present when
                                  currency is usd.
                                enum:
                                  - checking
                                  - savings
                                  - instapay
                                  - pesonet
                                example: checking
                                type: string
                                x-enumNames:
                                  - Checking
                                  - Savings
                                  - Instapay
                                  - Pesonet
                              routingNumber:
                                description: >-
                                  The 9-digit ABA routing number (also known as
                                  routing transit number) that identifies the US
                                  financial institution. Present when currency
                                  is usd.
                                example: '021000021'
                                type: string
                            required:
                              - accountNumber
                              - routingNumber
                              - accountType
                            type: object
                          - properties:
                              accountNumber:
                                description: >-
                                  The account number for SWIFT transfers
                                  (masked, last 4 characters visible). Present
                                  when currency is usd and networks is
                                  ["swift"].
                                example: '******7890'
                                type: string
                              bic:
                                description: >-
                                  The BIC/SWIFT code of the beneficiary bank.
                                  Present when currency is usd and networks is
                                  ["swift"].
                                example: DEUTDEFF
                                type: string
                              intermediaryBics:
                                description: >-
                                  Ordered list of BIC/SWIFT codes for
                                  intermediary correspondent banks, if any were
                                  set on this account. Omitted from the response
                                  when no intermediary BICs are set.
                                example:
                                  - CHASUS33
```

--------------------------------

### OpenAPI Specification for GET /v2/virtual-account

Source: https://docs.spherepay.co/api-reference/virtual-account/get

The complete OpenAPI 3.0.0 definition for the Sphere API's GET /v2/virtual-account endpoint. It lists the production server, bearer security, and response schemas including 200, 400, 404, and 422 responses with example error payloads.

```yaml
openapi: 3.0.0
info:
  contact: {}
  description: The Sphere REST API for payments, transfers, and accounts.
  title: Sphere API
  version: '2'
servers:
  - description: Production
    url: https://api.spherepay.co
security:
  - bearer: []
tags: []
paths:
  /v2/virtual-account:
    get:
      summary: List Virtual Accounts
      description: List all active virtual accounts for the authenticated application.
      operationId: getV2VirtualAccount
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListVirtualAccountsResponseDto'
          description: ''
        '400':
          content:
            application/json:
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Invalid request parameters
                    status: 400
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Resource not found
                    status: 404
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Not Found
        '422':
          content:
            application/json:
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    code: validation/failed
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Validation failed
                    errors:
                      - detail: Invalid email format
                        pointer: /email
                      - detail: Name is required
                        pointer: /name
                    status: 422
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Unprocessable Entity - Validation Error
components:
  schemas:
    ListVirtualAccountsResponseDto:
      items:
        description: >-
          A virtual account provides deposit instructions (bank details) that
          automatically convert incoming fiat deposits to crypto. See the
          [Virtual Accounts guide](/concepts/automation/onramper-accounts).
        properties:
          active:
            description: >-
              Whether the virtual account is currently active and accepting
              deposits.
            example: true
            type: boolean
          created:
            description: Timestamp when the virtual account was created (ISO 8601).
            example: '2025-01-15T10:30:00.000Z'
            type: string
          customer:
            description: The customer ID who owns the virtual account.
            example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7
            type: string
          depositInstructions:
            description: >-
              Bank account details that depositors should use to send fiat funds
              into the virtual account.
            properties:
              bankAccountNumber:
                description: >-
                  Bank account number for deposits (USD accounts). Null for EUR
                  accounts.
                example: '9876543210'
                nullable: true
                type: string
              bankAddress:
                description: Address of the bank holding the virtual account.
                example: 1801 Main St, Kansas City, MO 64108
                type: string
              bankBeneficiaryAddress:
                description: Address of the beneficiary on the account.
                example: 123 Finance St, San Francisco, CA 94105
                type: string
              bankBeneficiaryName:
                description: Name of the beneficiary on the account.

```

--------------------------------

### On-ramp via Starknet (JSON request)

Source: https://docs.spherepay.co/changelog

Example transfer request for on-ramping USD from a bank account via wire to a Starknet wallet. Use "network": "wire" in the source and "network": "starknet" in the destination.

```json
{
  "customer": "customer_098xxxxxxxxxxxxxxxxxxxxxxxxxxxfbb",
  "amount": "2",
  "source": {
    "id": "bankAccount_cabxxxxxxxxxxxxxxxxxxxxcxxxxx42c",
    "network": "wire",
    "currency": "usd"
  },
  "destination": {
    "id": "wallet_81bxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx9f3",
    "network": "starknet",
    "currency": "usdc"
  }
}
```

--------------------------------

### OpenAPI 3.0 spec for GET /v2/virtual-account/{virtualAccountId}

Source: https://docs.spherepay.co/api-reference/virtual-account/get-id

YAML specification for the endpoint, defining parameters, success response, and error responses with example values.

```yaml
openapi: 3.0.0
info:
  contact: {}
  description: The Sphere REST API for payments, transfers, and accounts.
  title: Sphere API
  version: '2'
servers:
  - description: Production
    url: https://api.spherepay.co
security:
  - bearer: []
tags: []
paths:
  /virtual-account/{virtualAccountId}:
    get:
      summary: Get a Virtual Account
      description: Retrieve a virtual account by its ID.
      operationId: getV2VirtualAccountByVirtualAccountId
      parameters:
        - in: path
          name: virtualAccountId
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualAccountResponseDto'
          description: ''
        '400':
          content:
            application/json:
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Invalid request parameters
                    status: 400
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Resource not found
                    status: 404
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Not Found
        '422':
          content:
            application/json:
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    code: validation/failed
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Validation failed
                    errors:
                      - detail: Invalid email format
                        pointer: /email
                      - detail: Name is required
                        pointer: /name
                    status: 422
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Unprocessable Entity - Validation Error
components:
  schemas:
    VirtualAccountResponseDto:
      properties:
        active:
          description: >-
            Whether the virtual account is currently active and accepting
            deposits.
          example: true
          type: boolean
        created:
          description: Timestamp when the virtual account was created (ISO 8601).
          example: '2025-01-15T10:30:00.000Z'
          type: string
        customer:
          description: The customer ID who owns the virtual account.
          example: customer_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7
          type: string
        depositInstructions:
          description: >-
            Bank account details that depositors should use to send fiat funds
            into the virtual account.
          properties:
            bankAccountNumber:
              description: >-
                Bank account number for deposits (USD accounts). Null for EUR
                accounts.
              example: '9876543210'
              nullable: true
              type: string
            bankAddress:
              description: Address of the bank holding the virtual account.
              example: 1801 Main St, Kansas City, MO 64108
              type: string
            bankBeneficiaryAddress:
              description: Address of the beneficiary on the account.
              example: 123 Finance St, San Francisco, CA 94105
              type: string
            bankBeneficiaryName:
              description: Name of the beneficiary on the account.
              example: Bridge Financial Inc.
              type: string
            bankName:
              description: Name of the bank holding the virtual account.
              example: Lead Bank
              type: string
            bankRoutingNumber:
              description: >-
```

--------------------------------

### Poll customer verification status

Source: https://docs.spherepay.co/concepts/onboarding/kyc-via-link

GET /v2/customer/{id} to poll verification status. Example response shows approved status with empty required and errors.

```bash
GET https://api.spherepay.co/v2/customer/{id}
```

```json
{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "approved",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number",
          "identity_document",
          "liveness_report_document"
        ],
        "pending": [],
        "required": [],
        "errors": []
      }
    }
  ],
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "type": "individual"
}
```

--------------------------------

### POST /v2/customer with EEA+ fields

Source: https://docs.spherepay.co/concepts/onboarding/individual-kyc

Example request to create an individual customer with the additional EEA+ fields under personalInformation. The fields are not hard-required at creation, but must be supplied before verification. Include other required fields (email, phone, full address) as usual.

```json
{
  "type": "individual",
  "firstName": "Anna",
  "lastName": "Lindqvist",
  "address": { "country": "SWE" },
  "personalInformation": {
    "countryOfBirth": "FIN",
    "nationality": "SWE",
    "accountPurpose": "receive_salary"
  }
}
```

--------------------------------

### OpenAPI specification for GET /v2/quote/{id}

Source: https://docs.spherepay.co/api-reference/quote/get-id

YAML OpenAPI definition for the Sphere API endpoint that retrieves a quote by ID. Includes path parameter, response schemas, and error examples.

```yaml
openapi: 3.0.0
info:
  contact: {}
  description: The Sphere REST API for payments, transfers, and accounts.
  title: Sphere API
  version: '2'
servers:
  - description: Production
    url: https://api.spherepay.co
security:
  - bearer: []
tags: []
paths:
  /v2/quote/{id}:
    get:
      summary: Get a Quote
      description: Retrieve a single quote by its ID.
      operationId: getV2QuoteById
      parameters:
        - description: The unique quote ID.
          in: path
          name: id
          required: true
          schema:
            example: quote_d243ab2b1de4447d8a046d87fefe58cf
            pattern: ^quote_[a-z0-9]+$
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetQuoteResponseDto'
          description: ''
        '400':
          content:
            application/json:
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Invalid request parameters
                    status: 400
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Resource not found
                    status: 404
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Not Found
        '422':
          content:
            application/json:
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    code: validation/failed
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Validation failed
                    errors:
                      - detail: Invalid email format
                        pointer: /email
                      - detail: Name is required
                        pointer: /name
                    status: 422
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Unprocessable Entity - Validation Error
components:
  schemas:
    GetQuoteResponseDto:
      properties:
        created:
          description: The datetime the quote was created.
          example: '2025-01-01T00:00:00.000Z'
          format: date-time
          type: string
        customerId:
          description: The customer ID.
          example: customer_d243ab2b1de4447d8a046d87fefe58cf
          type: string
        destination:
          properties:
            amount:
              description: The destination amount after exchange.
              example: '545.50'
              type: string
            currency:
              description: The destination currency.
              enum:
                - usdc
                - usdt
                - eurc
                - usd
                - eur
                - brl
                - mxn
                - mxn
              example: brl
              type: string
            exchangeRate:
              description: The exchange rate applied to convert source to destination.
              example: '5.455'
              type: string
            network:
              description: The destination network.
              example: pix
              oneOf:
                - description: A blockchain network.
                  enum:
                    - sol
                    - fogo
                    - ethereum
                    - arbitrum
                    - polygon
                    - base
                    - avalanche
                    - sui
                    - noble
                    - sei
                    - tron
                    - starknet
                    - aptos
                    - hyperliquid
                  example: polygon
                  type: string
                - enum:
                    - wire
                    - ach
                    - achPush
                    - achPull
                    - achSameDay
```

--------------------------------

### Batch stablecoin transfers (JavaScript)

Source: https://docs.spherepay.co/solutions/payroll

JavaScript example that fans out multiple stablecoin transfers in parallel for multiple employees. Uses Promise.all and a createTransfer function.

```javascript
const employees = [
  { customerId: "customer_employee_1", amount: "5000.00", walletId: "wallet_1" },
  { customerId: "customer_employee_2", amount: "4500.00", walletId: "wallet_2" },
  { customerId: "customer_employee_3", amount: "6000.00", walletId: "wallet_3" },
];

const transfers = await Promise.all(
  employees.map(emp =>
    createTransfer({
      amount: emp.amount,
      customer: emp.customerId,
      source: {
        type: "bank_account",
        id: COMPANY_BANK_ID,
        currency: "usd",
        network: "ach",
      },
      destination: {
        type: "wallet",
        id: emp.walletId,
        currency: "usdc",
        network: "sol",
      },
    })
  )
);
```

--------------------------------

### OpenAPI specification for GET /v2/customer/{id}

Source: https://docs.spherepay.co/api-reference/customer/get-id

YAML OpenAPI 3.0.0 specification for the Sphere API endpoint to retrieve a customer by ID. It defines the path parameter 'id' with an example customer ID, and documents 200, 400, 404, and 422 responses, including example error payloads for bad request, not found, and validation errors.

```yaml
openapi: 3.0.0
info:
  contact: {}
  description: The Sphere REST API for payments, transfers, and accounts.
  title: Sphere API
  version: '2'
servers:
  - description: Production
    url: https://api.spherepay.co
security:
  - bearer: []
tags: []
paths:
  /v2/customer/{id}:
    get:
      summary: Get a customer by ID
      description: Get information about a customer by their ID
      operationId: getV2CustomerById
      parameters:
        - description: Customer ID
          in: path
          name: id
          required: true
          schema:
            example: customer_f31121c389624d3697cbf3ea8830b7a4
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponseDto'
          description: ''
        '400':
          content:
            application/json:
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Invalid request parameters
                    status: 400
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Resource not found
                    status: 404
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Not Found
        '422':
          content:
            application/json:
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    code: validation/failed
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Validation failed
                    errors:
                      - detail: Invalid email format
                        pointer: /email
                      - detail: Name is required
                        pointer: /name
                    status: 422
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Unprocessable Entity - Validation Error
components:
  schemas:
    CustomerResponseDto:
      oneOf:
        - description: Response containing information about an individual customer.
          properties:
            createdAt:
              description: ISO 8601 formatted customer creation timestamp
              example: '2026-03-09T20:46:31.305Z'
              type: string
            dateOfBirth:
              description: >-
                The customer's date of birth in YYYY-MM-DD format (individual
                customers only).
              example: '1990-01-15'
              type: string
            email:
              description: Customer email address
              example: jane.smith@example.com
              type: string
            firstName:
              description: Customer first name (individual customers only)
              example: Jane
              type: string
            id:
              description: Customer ID
              example: customer_f31121c389624d3697cbf3ea8830b7a4
              type: string
            lastName:
              description: Customer last name (individual customers only)
              example: Smith
              type: string
            meta:
              additionalProperties: {}
              type: object
            personalInformation:
              description: >-
                Personal information for an individual customer, echoed back
                from the most recent submission. The tax identification number
                is omitted from responses for privacy.
              properties:
                accountPurpose:
                  type: string
                accountPurposeDescription:
                  description: >-
```

--------------------------------

### Create a customer with POST /v2/customer

Source: https://docs.spherepay.co/get-started/first-api-call

Creates an individual customer via POST /v2/customer. The request must include contact details and tax identification information. The response returns the customer object with a system-generated id and a verificationProfiles array showing KYC status as incomplete. The customer must complete KYC and reach approved status before any transfer can be created.

```bash
curl -X POST https://api.spherepay.co/v2/customer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "address": {
      "line1": "233 South Wacker Drive",
      "line2": "Suite 4700",
      "city": "Chicago",
      "postalCode": "60606",
      "state": "IL",
      "country": "USA"
    },
    "personalInformation": {
      "taxIdentificationNumber": "123456789",
      "taxIdentificationNumberType": "ssn",
      "taxIdentificationNumberCountry": "USA"
    }
  }'
```

```json
{
    "id": "customer_4fbb292cc6e447da8858e054d1937e7e",
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "verificationProfiles": [
        {
            "name": "kyc_profile_a",
            "status": "incomplete",
            "criteria": {
                "complete": [],
                "pending": [],
                "required": [],
                "errors": []
            }
        }
    ],
    "createdAt": "2026-03-03T21:25:03.102Z",
    "updatedAt": "2026-03-03T21:25:03.102Z",
    "type": "individual"
}
```

--------------------------------

### GET /v2/customer/{id}

Source: https://docs.spherepay.co/concepts/onboarding/verification-profile

Retrieves the current verification status of a customer, including the state of each required criterion. Use this endpoint to poll for approval before proceeding with payment method registration and transfer setup.

```APIDOC
## GET /v2/customer/{id}

### Description
Retrieves the current state of a customer's verification profile, including the status of each required criterion.

### Method
GET

### Endpoint
https://api.spherepay.co/v2/customer/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer.

### Response
#### Success Response (200)
- **id** (string) - The customer's unique identifier.
- **email** (string) - The customer's email address.
- **phone** (string) - The customer's phone number.
- **verificationProfiles** (array) - List of verification profiles.
  - **name** (string) - The name of the verification profile.
  - **status** (string) - The current status of the profile (e.g., "approved").
  - **criteria** (object) - Contains arrays of criteria items.
    - **complete** (array) - List of completed criteria.
    - **pending** (array) - List of pending criteria.
    - **required** (array) - List of required criteria.
    - **errors** (array) - List of errors.
- **createdAt** (string) - Timestamp of creation.
- **updatedAt** (string) - Timestamp of last update.
- **type** (string) - The type of customer (e.g., "individual").

#### Response Example
{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "approved",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number",
          "identity_document",
          "liveness_report_document"
        ],
        "pending": [],
        "required": [],
        "errors": []
      }
    }
  ],
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "type": "individual"
}
```

--------------------------------

### Register wallet response example

Source: https://docs.spherepay.co/concepts/transfers/wallets

JSON response from the wallet registration endpoint. Contains the wallet id, address, network, customerId, and timestamps. Store the returned id for future transfers.

```json
{
  "id": "wallet_1234567890",
  "address": "0x1234567890123456789012345678901234567890",
  "network": "sol",
  "customerId": "customer_1234567890",
  "created": "2026-01-25T12:00:00.000Z",
  "updated": "2026-01-25T12:00:00.000Z"
}
```

--------------------------------

### Poll verification result (approved business)

Source: https://docs.spherepay.co/concepts/onboarding/business-kyb

Example response from GET /v2/customer/{id} showing an approved business customer. When required is empty and status is approved, the business is fully onboarded and ready to transfer.

```json
{
  "id": "customer_2f283221a9d44ada800ac7f11f640402",
  "email": "contact@acmecorp.example.com",
  "verificationProfiles": [
    {
      "name": "kyb_profile_a",
      "status": "approved",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "operating_address",
          "registered_address",
          "legal_name",
          "identification_number",
          "business_representatives",
          "incorporation_cert_document",
          "shareholder_registry_document",
          "proof_of_address_document"
        ],
        "pending": [],
        "required": [],
        "errors": []
      }
    }
  ],
  "type": "business"
}
```

--------------------------------

### POST /v2/customer/kyc-link

Source: https://docs.spherepay.co/api-reference/customer/kyc-link

Creates a customer via the hosted onboarding link flow and returns a KYC link with its expiry.

```APIDOC
## POST /v2/customer/kyc-link

### Description
Create a customer via the hosted onboarding link flow. Returns a KYC link and its expiry.

### Method
POST

### Endpoint
/v2/customer/kyc-link

### Parameters
#### Request Body
- **type** (string) - Required - The type of customer to onboard. Enum: individual, business.
- **email** (string) - Required - The customer email address. Format: email, maxLength: 254.
- **phone** (string) - Optional - The customer phone number in E.164 format. Pattern: ^\+(?:[0-9]){6,14}[0-9]$
- **address** (object) - Required - The customer's address. For individual customers this is the residential address; for business customers this is the registered business address.
  - **line1** (string) - Required - The first line of the street address. maxLength: 255, minLength: 1.
  - **line2** (string) - Optional - The second line of the street address (apartment, suite, etc.). maxLength: 255.
  - **city** (string) - Required - The city name. maxLength: 255, minLength: 1.
  - **state** (string) - Optional - The state or province code (ISO3166-2 subdivision code). Required for countries that have states/provinces.
  - **postalCode** (string) - Optional - The postal or ZIP code. Required for countries that use postal codes.
  - **country** (string) - Required - The ISO3166-1 Alpha-3 country code (e.g., USA, GBR, CAN).

### Request Example
{
  "type": "individual",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "address": {
    "line1": "233 South Wacker Drive",
    "line2": "Suite 4700",
    "city": "Chicago",
    "state": "IL",
    "postalCode": "60606",
    "country": "USA"
  }
}

### Response
#### Success Response (201)
- **GenerateKycUrlResponseDto** (object) - The response containing the KYC link and its expiry.

#### Response Example
{
  "kycLink": "https://onboard.spherepay.co/...",
  "expiresAt": "2025-01-01T00:00:00Z"
}

#### Error Responses
- **400 Bad Request** - Invalid request parameters.
  - **code** (string) - Error code, e.g., "address/invalid".
  - **correlationId** (string) - Correlation ID for tracking.
  - **detail** (string) - Error detail.
  - **status** (integer) - HTTP status code.
- **404 Not Found** - Resource not found.
  - **code** (string) - Error code, e.g., "resource/not-found".
  - **correlationId** (string) - Correlation ID for tracking.
  - **detail** (string) - Error detail.
  - **status** (integer) - HTTP status code.
- **422 Unprocessable Entity** - Validation failed.
  - **code** (string) - Error code, e.g., "validation/failed".
  - **correlationId** (string) - Correlation ID for tracking.
  - **detail** (string) - Error detail.
  - **errors** (array) - List of validation errors.
    - **detail** (string) - Error description.
    - **pointer** (string) - Field path that failed validation.
  - **status** (integer) - HTTP status code.
```

--------------------------------

### POST /api-reference/customer/kyc-link

Source: https://docs.spherepay.co/api-reference/customer/kyc-link

Creates a customer via the hosted onboarding link flow and returns a KYC link and its expiry. Use this endpoint to create a customer and generate a hosted KYC link in a single request.

```APIDOC
## POST /api-reference/customer/kyc-link

### Description
Creates a customer via the hosted onboarding link flow and returns a KYC link and its expiry. Use this endpoint to create a customer and generate a hosted KYC link in a single request.

### Method
POST

### Endpoint
/api-reference/customer/kyc-link

### Parameters
#### Request Body
- **type** (string) - Required - The customer's type.
- **email** (string) - Required - The customer's email address.
- **phone** (string) - Required - The customer's phone number.
- **address** (object) - Required - The customer's address.

### Request Example
{
  "type": "individual",
  "email": "customer@example.com",
  "phone": "+1234567890",
  "address": {
    "line1": "123 Main St",
    "city": "Anytown",
    "country": "US"
  }
}

### Response
#### Success Response (200)
- **customerId** (string) - The ID of the newly created customer.
- **kycLink** (string) - The hosted verification URL.
- **expiresAt** (string) - The expiry timestamp of the KYC link.

#### Response Example
{
  "customerId": "cus_123456",
  "kycLink": "https://verify.spherepay.co/abc123",
  "expiresAt": "2025-01-01T00:00:00Z"
}
```

--------------------------------

### Full example: minimal HTML page

Source: https://docs.spherepay.co/widget/setup

A minimal HTML page that embeds the Ramp Widget. It includes the hosted script with onload attribute, the initializer function, and the container element.

```html
<html>
  <head>
    <script
      type="module"
      crossorigin
      src="https://spherepay.co/packages/sphere-ramp/index.js"
      onload="initSphereRamp()"
    ></script>
    <script>
      function initSphereRamp() {
        new RampWidget({
          containerId: 'container',
          applicationId: 'YOUR_APPLICATION_ID',
        })
      }
    </script>
  </head>
  <body>
    <div id="container"></div>
  </body>
</html>
```