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

# Add KYC Data

> Completes the PAN-only KYC required for the beneficiary (receiving customer) of a remittance payout.

<Prompt description="Remittance Beneficiary KYC" actions={["cursor"]}>
  Integrate the DollarPe Remittance Beneficiary KYC endpoint into my application.

  Endpoint: POST /kyc/remittance-beneficiary-kyc
  Base URL: [https://api.dollarpe.in](https://api.dollarpe.in) (production) | [https://sandbox.dollarpe.in](https://sandbox.dollarpe.in) (sandbox)

  Auth headers required on every request:

  * X-API-KEY: your API key
  * X-TIMESTAMP: current Unix time in seconds
  * X-SIGNATURE: Base64(HMAC-SHA256(X-API-KEY + X-TIMESTAMP + sortedJSONBody, apiSecret))

  Remittance payout flow:

  1. POST /customer/create (alpha\_3\_country\_code: "IND") → get customer\_id
  2. POST /kyc/remittance-beneficiary-kyc → complete the beneficiary's PAN-only KYC
  3. POST /bank/create → add the beneficiary's bank account → get bank\_id
  4. POST /kyc/remitter/create → register the sending party → get remitter\_id
  5. POST /remittance-payout/quotation with receiving\_amount → get quotation\_id
  6. POST /remittance-payout/initiate → create the order
  7. Poll GET /payout/{payout_id} or listen to webhooks for status updates

  Task: Write a typed function that:

  1. Accepts customer\_id and tax\_number (PAN)
  2. Builds the signed auth headers
  3. Calls POST /kyc/remittance-beneficiary-kyc
  4. Returns the KYC record id and customer\_id
  5. Handles 400 (missing/invalid fields) and 500 errors

  Language: TypeScript
</Prompt>

## Error Codes and Messages

| API Status Code | Response              | Reason                                   |
| --------------- | --------------------- | ---------------------------------------- |
| 400             | Bad Request           | `customer_id` or `tax_number` is missing |
| 400             | Bad Request           | `tax_number` format is invalid           |
| 500             | Internal Server Error | Internal Server Error                    |


## OpenAPI

````yaml POST /kyc/remittance-beneficiary-kyc
openapi: 3.1.0
info:
  title: DollarPe API
  description: API for DollarPe - Customer, Payout, and Webhook services
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://sandbox.dollarpe.xyz/pos/api/v1
    description: Payout API Base URL
    variables:
      base_url:
        default: https://sandbox.dollarpe.xyz
  - url: https://sandbox.dollarpe.xyz/cms/api/v1
    description: Customer API Base URL
    variables:
      base_url:
        default: https://sandbox.dollarpe.xyz
security:
  - ApiKeyAuth: []
    TimestampAuth: []
    SignatureAuth: []
tags:
  - name: Customer
    description: Customer related operations
    x-displayName: Customer
    x-traitTag: true
  - name: Payout
    description: Payout related operations
  - name: Webhooks
    description: Webhook related operations
  - name: Widget
    description: Hosted buy/sell widget session initialization
paths:
  /kyc/remittance-beneficiary-kyc:
    post:
      tags:
        - KYC
      description: >-
        Completes the PAN-only KYC required for the beneficiary (receiving
        customer) of a remittance payout by submitting the customer's tax number
        (PAN). Run this after creating the customer and before adding their bank
        account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
                - tax_number
              properties:
                customer_id:
                  type: string
                  format: uuid
                  description: The unique identifier of the customer
                  example: 638d9a52-9427-460e-99ba-948d46ce349c
                tax_number:
                  type: string
                  description: The customer's tax number (PAN for India).
                  example: HCDPS3890E
      responses:
        '200':
          description: Remittance sender KYC recorded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Success
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier of the KYC record
                        example: ea6899a3-abb9-4418-8878-e23f5021e38f
                      customer_id:
                        type: string
                        format: uuid
                        example: 638d9a52-9427-460e-99ba-948d46ce349c
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Bad Request
                  error:
                    type: object
                    example:
                      tax_number:
                        - This field is required.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Internal Server Error
      servers:
        - url: https://sandbox.dollarpe.xyz/cms/api/v1
          description: KYC API Base URL
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key for authentication
    TimestampAuth:
      type: apiKey
      in: header
      name: X-TIMESTAMP
      description: Current timestamp in seconds since epoch
    SignatureAuth:
      type: apiKey
      in: header
      name: X-SIGNATURE
      description: HMAC SHA256 signature of the request encoded in Base64

````