> ## Documentation Index
> Fetch the complete documentation index at: https://docs.globalstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a customer

> Creates a new customer scoped to the calling merchant's integration.

### Body

- `type` — required. One of `individual`, `business`.
- `name` — required. Full name of the customer. Max 255 chars.
- `email` — required. Valid email. Max 255 chars. Per-integration uniqueness
  is enforced case-insensitively.
- `country_code` — required. ISO-3166-1 alpha-2 (e.g. `NG`, `KE`). Countries on the
  compliance prohibited list are rejected with `400 prohibited_country`.
- `metadata` — optional. Free-form `Record<string, string>`.
- `merchant_reference` — optional. Max 128 chars. Auto-generated as
  `ref_<ULID>` when omitted. Per-integration unique.
- `profile` — optional object carrying the identity fields required to convert
  (onramp/offramp). When supplied it must be complete for the customer `type`:
  - `individual` requires `phone`, `address`, `date_of_birth`, `id_number`, `id_type`.
  - `business` requires `phone`, `business_licence`.

  Fields: `phone`, `address`, `id_number`, `id_type`, `business_licence` are strings;
  `date_of_birth` must be `mm/dd/yyyy`. A supplied-but-incomplete `profile` for the
  `type` returns `400 invalid_input`.

### Example

```
POST /v1/customers
{
  "type": "individual",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "country_code": "NG",
  "profile": {
    "phone": "+2348012345678",
    "address": "1 Marina Rd, Lagos",
    "date_of_birth": "01/15/1990",
    "id_number": "A12345678",
    "id_type": "passport"
  }
}
```




## OpenAPI

````yaml /api-reference/openapi.json post /v1/customers
openapi: 3.0.0
info:
  title: GlobalStack API
  version: 1.0.0
  description: >
    # Introduction


    GlobalStack API for cross-border payments powered by stablecoin rails.


    Getting started: authenticate with a Bearer token, make your first call to

    `GET /v1/currencies`, and explore.


    **Key operations:**


    - **Onramp** — convert external fiat into crypto credited to a wallet.

    - **Offramp** — convert crypto from a wallet into fiat delivered to a
    beneficiary.

    - **Conversion** — move value between two wallets belonging to the same
    customer.

    - **Transfer** — send crypto from a wallet to an external address.

    - **Deposit** — receive external crypto into a wallet via a deposit address.


    See the sections below for authentication, response shape, idempotency,

    references, metadata, and webhooks.


    ## Authentication


    All API requests require a Bearer token in the `Authorization` header:


    ```

    Authorization: Bearer gsa_sk_live_your_api_key

    ```


    API keys use the `gsa_sk_live_` prefix.


    API keys are scoped to a single merchant account. All resources created with

    a key belong to that merchant. Keep your keys secret — do not expose them in

    client-side code or public repositories.


    To rotate a key, generate a new one from your dashboard and update your

    integration before revoking the old key.


    ## API Response Shape


    Every response — success or failure — follows the same envelope:


    ```json

    {
      "status": true,
      "message": "Onramp created successfully",
      "code": "ok",
      "data": { },
      "meta": {
        "request_id": "req_01ABC...",
        "timestamp": "2026-04-22T02:00:00Z",
        "version": "1"
      }
    }

    ```


    **Fields:**


    - `status` (boolean) — whether the HTTP call succeeded. This is not the
      business status of the underlying resource.
    - `message` (string) — human-readable explanation for developers and logs.
      Do not show to end users.
    - `code` (string) — stable machine-readable result. `ok` on success, or an
      error code like `bad_request`.
    - `data` — the resource payload on success (object, array, or scalar).
    `null`
      on failure.
    - `meta` — request-scoped metadata, always present. Includes `request_id`
      (quote this in support tickets), `timestamp`, and `version`. On list
      endpoints, also includes `page`, `per_page`, `total`, `has_more`. On
      validation errors, includes `errors` array and `next_steps`.

    Error responses include `next_steps` in `meta` with an `action` string and a

    `docs_url` link:


    ```json

    {
      "status": false,
      "message": "Your request has validation errors.",
      "code": "bad_request",
      "data": null,
      "meta": {
        "request_id": "req_01ABC...",
        "timestamp": "2026-04-22T02:00:00Z",
        "version": "1",
        "errors": [
          { "field": "amount", "code": "required", "message": "Amount is required." }
        ],
        "next_steps": {
          "action": "Review the request and retry with corrected parameters.",
          "docs_url": "https://docs.globalstack.io/errors#bad_request"
        }
      }
    }

    ```


    ## Idempotency


    Pass an `Idempotency-Key` header on any create endpoint to make the request

    safely retryable:


    ```

    Idempotency-Key: your-unique-key-here

    ```


    **Rules:**


    - Same key + same body = returns the original response (no side effects).

    - Same key + different body = returns `idempotency_conflict` (409).

    - Keys are scoped to your merchant account.

    - Keys expire after 24 hours.


    Use idempotency keys for any operation that creates a resource or moves

    money. This protects against network retries, duplicate webhooks, and

    client-side retry loops.


    ## Rate Limits


    Requests over the rate limit are rejected with HTTP `429` and the error code

    `rate_limited`:


    ```json

    {
      "status": false,
      "message": "Too many requests. Slow down and retry shortly.",
      "code": "rate_limited"
    }

    ```


    **Money-movement writes** (creating transfers, offramps, conversions, or

    wallet operations) are limited **per merchant account** — the budget is

    shared across all of your API keys and dashboard sessions. Reads are not

    limited.


    On a `429`, back off and retry with jitter; for money movement, reuse the

    same `Idempotency-Key` so the retry stays safe.


    ## Reference


    Every money movement operation (onramp, offramp, conversion, transfer)

    accepts an optional `reference` field — a merchant-supplied identifier that

    is unique per merchant account.


    ```json

    {
      "reference": "INV-2026-001",
      "wallet_id": "wal_..."
    }

    ```


    If you omit `reference`, the API generates one automatically (prefixed

    `ref_`).


    References are unique per merchant — attempting to create two operations

    with the same reference returns the existing operation (same behavior as

    idempotency, but permanent and not time-limited).


    Use `reference` to correlate GlobalStack operations with your own system

    records (invoices, orders, payouts).


    ## Metadata


    Most create endpoints accept an optional `metadata` object — a flat set of

    string key/value pairs stored on the resource:


    ```json

    {
      "metadata": {
        "order_id": "ord_12345",
        "customer_email": "alice@example.com"
      }
    }

    ```


    Metadata is returned on every GET response and in webhook payloads. It is

    not used by GlobalStack for processing — it exists for your own

    record-keeping.


    Resources that accept metadata: customers, wallets, senders, beneficiaries,

    wallet credentials, deposit addresses, onramps, offramps, conversions, and

    transfers.


    ## Webhook Signatures


    Every webhook delivery is signed so you can verify it came from GlobalStack
    and

    was not tampered with in transit. Signatures follow the

    [Svix](https://docs.svix.com/receiving/verifying-payloads/how) standard, so
    you

    can verify them with any Svix library — or manually with the construction
    below.


    Each delivery carries three headers:


    ```

    svix-id: msg_2gT8sV...          # unique message id (the body's event_id,
    prefixed msg_)

    svix-timestamp: 1718960400      # unix seconds when the delivery was signed

    svix-signature: v1,g0hM9SsE...  # space-separated list of
    v1,<base64-signature>

    ```


    Your signing secret (prefixed `whsec_`) is returned in plaintext **exactly

    once** — when you create a webhook endpoint or rotate its secret. Store it

    securely; you cannot retrieve it again.


    **Verify with a Svix library (recommended):**


    ```python

    from svix.webhooks import Webhook


    wh = Webhook(signing_secret)                            # the whsec_...
    value

    payload = wh.verify(raw_request_body, request_headers)  # raises on a bad
    signature

    ```


    **Verify manually:**


    1. Build the signed content by joining the id, timestamp, and the **raw**
       request body with dots:

       ```
       signed_content = svix_id + "." + svix_timestamp + "." + raw_body
       ```

    2. Take your signing secret, drop the `whsec_` prefix, and base64-decode the
       remainder — those bytes are your HMAC key.

    3. Compute `base64(HMAC-SHA256(key, signed_content))`.


    4. The `svix-signature` header is a space-separated list of `v1,<signature>`
       entries (an endpoint can have more than one valid secret during a rotation).
       Compare your computed value against each entry's signature — the part after
       `v1,` — using a constant-time comparison, and accept if any matches.

    5. Reject deliveries whose `svix-timestamp` differs from your current time
    by
       more than a few minutes, to guard against replay.

    The body's `event_id` equals the `svix-id` without its `msg_` prefix, so you
    can

    use either to deduplicate redelivered events.


    ## Request IDs


    Every response carries an `X-Request-Id` header (also surfaced in

    `meta.request_id`). Include the value when reporting issues — it scopes

    backend logs to your specific request.


    You may also send your own `X-Request-Id` header. Values matching

    `^[A-Za-z0-9_-]{1,128}$` are honored verbatim; anything else is replaced
    with

    a generated id.


    ## Versioning


    Public endpoints are versioned under `/v1/`. Breaking changes ship under a
    new

    major version; additive changes (new fields, new endpoints) ship under the

    existing version.
  contact:
    name: Paystack Cross-Border
    url: https://globalstack.io
servers:
  - url: https://api.globalstack.io
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Supported Countries
  - name: Supported Currencies
  - name: Customers
  - name: Wallets
  - name: Beneficiaries
  - name: Quotes
  - name: Onramps
  - name: Offramps
  - name: Conversions
  - name: Transfers
  - name: Transactions
  - name: Notification Webhooks
  - name: Me
paths:
  /v1/customers:
    post:
      tags:
        - Customers
      summary: Create a customer
      description: >
        Creates a new customer scoped to the calling merchant's integration.


        ### Body


        - `type` — required. One of `individual`, `business`.

        - `name` — required. Full name of the customer. Max 255 chars.

        - `email` — required. Valid email. Max 255 chars. Per-integration
        uniqueness
          is enforced case-insensitively.
        - `country_code` — required. ISO-3166-1 alpha-2 (e.g. `NG`, `KE`).
        Countries on the
          compliance prohibited list are rejected with `400 prohibited_country`.
        - `metadata` — optional. Free-form `Record<string, string>`.

        - `merchant_reference` — optional. Max 128 chars. Auto-generated as
          `ref_<ULID>` when omitted. Per-integration unique.
        - `profile` — optional object carrying the identity fields required to
        convert
          (onramp/offramp). When supplied it must be complete for the customer `type`:
          - `individual` requires `phone`, `address`, `date_of_birth`, `id_number`, `id_type`.
          - `business` requires `phone`, `business_licence`.

          Fields: `phone`, `address`, `id_number`, `id_type`, `business_licence` are strings;
          `date_of_birth` must be `mm/dd/yyyy`. A supplied-but-incomplete `profile` for the
          `type` returns `400 invalid_input`.

        ### Example


        ```

        POST /v1/customers

        {
          "type": "individual",
          "name": "Alice Johnson",
          "email": "alice@example.com",
          "country_code": "NG",
          "profile": {
            "phone": "+2348012345678",
            "address": "1 Marina Rd, Lagos",
            "date_of_birth": "01/15/1990",
            "id_number": "A12345678",
            "id_type": "passport"
          }
        }

        ```
      operationId: CustomerController.create
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
            pattern: ^[A-Za-z0-9_\-]{8,255}$
          description: >-
            Optional client-supplied key. Identical key + identical body within
            24h replays the original response. Identical key + different body
            returns 409 idempotency_conflict. The hash is over raw bytes —
            clients retrying must send the byte-identical body; a re-serialised
            JSON payload will produce a different hash and a 409. Strongly
            recommended for retry-safe clients.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerDto'
        description: CreateCustomerDto
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessEnvelope'
                  - type: object
                    required:
                      - data
                      - meta
                    properties:
                      message:
                        type: string
                        example: Customer created successfully
                      data:
                        $ref: '#/components/schemas/CustomerResponse'
                      meta:
                        $ref: '#/components/schemas/ApiResponseMetaSchema'
          description: Customer created successfully
        '400':
          description: >-
            Bad request — possible codes: `invalid_input` (request body failed
            validation, including a supplied-but-incomplete `profile` for the
            customer type, or a `date_of_birth` not in mm/dd/yyyy format, or a
            malformed Idempotency-Key header), `prohibited_country` (the
            `country_code` is not available for onboarding). Branch on the
            `code` field of the response envelope.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - invalid_input
                          - prohibited_country
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - authentication_failed
        '409':
          description: >-
            Conflict — possible codes: `duplicate_resource` (merchant_reference,
            email, or another unique field already in use),
            `idempotency_conflict` (Idempotency-Key reused with a different
            request body), `idempotency_in_progress` (a request with the same
            Idempotency-Key is still in flight). Branch on the `code` field of
            the response envelope.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - duplicate_resource
                          - idempotency_conflict
                          - idempotency_in_progress
        '500':
          description: FX Engine upstream is unreachable
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - external_service_unavailable
components:
  schemas:
    CreateCustomerDto:
      properties:
        type:
          enum:
            - individual
            - business
          type: string
        name:
          maxLength: 255
          type: string
          minLength: 1
        email:
          maxLength: 255
          type: string
          format: email
        country_code:
          pattern: ^[A-Z]{2}$
          type: string
        metadata:
          type: object
        merchant_reference:
          maxLength: 128
          type: string
        profile:
          $ref: '#/components/schemas/CustomerProfileDto'
      type: object
      required:
        - type
        - name
        - email
        - country_code
    ApiSuccessEnvelope:
      properties:
        status:
          type: boolean
          enum:
            - true
          example: true
        message:
          type: string
          description: Human-readable summary
          example: Resource fetched successfully
        code:
          type: string
          enum:
            - ok
          example: ok
      type: object
      required:
        - status
        - message
        - code
    CustomerResponse:
      properties:
        id:
          type: string
          description: GlobalStack customer external id (prefixed cust_).
          example: cust_01HXYZABC1234567890ABCDEFG
        type:
          enum:
            - individual
            - business
          type: string
          description: Customer type
          example: individual
        name:
          type: string
          description: Customer full or business name
          example: Alice Johnson
        email:
          format: email
          type: string
          example: alice@example.com
        merchant_reference:
          type: string
          description: >-
            Caller-supplied or auto-generated identifier (ref_…) unique per
            integration.
          example: ref_01HXYZ4K5ABCDEFGHJKLMNPQRS
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code
          example: NG
        tier:
          enum:
            - tier_0
            - tier_1
            - tier_2
          type: string
          description: KYC tier; starts at tier_0
          example: tier_0
        kyc_status:
          enum:
            - not_started
            - pending
            - in_progress
            - approved
            - rejected
            - expired
          type: string
          description: Current KYC status
          example: not_started
        metadata:
          type: object
          description: Merchant-supplied opaque metadata. Values are stored as strings.
          example:
            source: checkout
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
          example: '2026-04-16T16:14:08.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-04-16T16:14:08.000Z'
        profile:
          $ref: '#/components/schemas/CustomerProfileResponse'
          description: Merchant-provided identity fields (only fields that were supplied).
      type: object
      required:
        - id
        - type
        - name
        - email
        - merchant_reference
        - country_code
        - tier
        - kyc_status
        - metadata
        - created_at
        - updated_at
    ApiResponseMetaSchema:
      properties:
        request_id:
          type: string
          description: ULID-prefixed identifier for this request
          example: req_01HXYZ4K5ABCDEFGHJKLMNPQRS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-14T15:43:55.732Z'
        version:
          type: string
          description: Major API version parsed from /vN/
          example: '1'
      type: object
      required:
        - request_id
        - timestamp
        - version
    ApiErrorEnvelope:
      properties:
        status:
          type: boolean
          enum:
            - false
          example: false
        message:
          type: string
          description: Human-readable failure summary
          example: Resource not found
        code:
          type: string
          description: Stable error code for branching logic
          example: not_found
        data:
          type: object
          nullable: true
          example: null
        meta:
          $ref: '#/components/schemas/ApiErrorMetaSchema'
      type: object
      required:
        - status
        - message
        - code
        - data
        - meta
    CustomerProfileDto:
      properties:
        phone:
          maxLength: 32
          type: string
          minLength: 1
        address:
          maxLength: 255
          type: string
          minLength: 1
        date_of_birth:
          pattern: ^(0[1-9]|1[0-2])\/(0[1-9]|[12]\d|3[01])\/\d{4}$
          type: string
        id_number:
          maxLength: 64
          type: string
          minLength: 1
        id_type:
          maxLength: 64
          type: string
          minLength: 1
        business_licence:
          maxLength: 64
          type: string
          minLength: 1
      type: object
    CustomerProfileResponse:
      properties:
        phone:
          type: string
          description: Merchant-provided phone number
          example: '+2348012345678'
        address:
          type: string
          description: Merchant-provided residential address
          example: 1 Marina Rd, Lagos
        date_of_birth:
          type: string
          description: Merchant-provided date of birth (mm/dd/yyyy)
          example: 01/15/1990
        id_number:
          type: string
          description: Merchant-provided ID document number
          example: A12345678
        id_type:
          type: string
          description: Merchant-provided ID document type
          example: passport
        business_licence:
          type: string
          description: Merchant-provided business registration number
          example: RC123456
      type: object
    ApiErrorMetaSchema:
      properties:
        next_steps:
          $ref: '#/components/schemas/NextStepsSchema'
        request_id:
          type: string
          description: ULID-prefixed identifier for this request
          example: req_01HXYZ4K5ABCDEFGHJKLMNPQRS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-14T15:43:55.732Z'
        version:
          type: string
          description: Major API version parsed from /vN/
          example: '1'
      type: object
      required:
        - next_steps
        - request_id
        - timestamp
        - version
    NextStepsSchema:
      properties:
        action:
          type: string
          description: Suggested action for the caller
          example: Verify the resource identifier and retry.
        docs_url:
          type: string
          format: uri
          example: https://docs.globalstack.io/errors#not_found
      type: object
      required:
        - action
        - docs_url
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key issued during merchant onboarding.

````