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

# Create a crypto payment refund address

> Creates a refund address-book entry that can be used as `destination.addressBookId` when refunding a crypto payment intent.

This endpoint is used for Circle Singapore (`CIRCLE_SG`) refund flow 2, where the refund goes to a different address while reusing the original payment's Travel Rule originator PII. Provide the original `paymentId` and a hosted VASP in `ownership.custody.vaspId`; the supplied VASP ID must match the VASP associated with the original payment sender.

Do not provide recipient `identity` in the request. Identity is derived from the original payment's Travel Rule originator PII.




## OpenAPI

````yaml openapi/payments.yaml post /v1/payments/refundAddresses
openapi: 3.0.2
info:
  version: ${version}
  title: Crypto Deposits API
  description: >
    The Circle Payments API allows you to take payments from your end users via
    traditional methods such as debit & credit cards and receive settlement in
    USDC.


    The Circle Payments API has been designed with any business or internet
    commerce in mind, not just crypto applications, and it's based on Circle's
    extensive experience processing millions of card payments since 2014.
servers:
  - url: https://api-sandbox.circle.com
  - url: https://api.circle.com
security: []
tags:
  - name: Payments
    description: Create, cancel, refund, and get updates on card payments.
  - name: Crypto Payment Intents
    description: Create and track intent for end user to pay via crypto.
  - name: Crypto Payment Customers
    description: >-
      Create and manage Travel Rule customers and customer wallets for crypto
      payment attribution.
  - name: Crypto Payment Refund Addresses
    description: Create refund address-book entries for crypto payment refunds.
paths:
  /v1/payments/refundAddresses:
    post:
      tags:
        - Crypto Payment Refund Addresses
      summary: Create a crypto payment refund address
      description: >
        Creates a refund address-book entry that can be used as
        `destination.addressBookId` when refunding a crypto payment intent.


        This endpoint is used for Circle Singapore (`CIRCLE_SG`) refund flow 2,
        where the refund goes to a different address while reusing the original
        payment's Travel Rule originator PII. Provide the original `paymentId`
        and a hosted VASP in `ownership.custody.vaspId`; the supplied VASP ID
        must match the VASP associated with the original payment sender.


        Do not provide recipient `identity` in the request. Identity is derived
        from the original payment's Travel Rule originator PII.
      operationId: createPaymentRefundAddress
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRefundAddressCreationRequest'
      responses:
        '201':
          description: >-
            Refund address successfully created, or original address replayed
            for a reused idempotency key.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                title: CreatePaymentRefundAddressResponse
                properties:
                  data:
                    $ref: '#/components/schemas/PaymentRefundAddress'
              examples:
                refundAddress:
                  value:
                    data:
                      id: 7418ddb1-1bbf-5506-88f9-209a25c63b8b
                      chain: ETH
                      address: '0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799'
                      metadata:
                        nickname: Refund recipient
                      identity:
                        type: individual
                        firstName: John
                        lastName: Doe
                      ownership:
                        type: third_party
                        custody:
                          type: hosted
                          vaspId: 581b9b20-28e1-464d-a257-e408733d0857
                      status: pending
                      createDate: '2026-06-30T12:00:00Z'
                      updateDate: '2026-06-30T12:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/NotAuthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    PaymentRefundAddressCreationRequest:
      type: object
      required:
        - idempotencyKey
        - chain
        - address
        - metadata
        - ownership
        - paymentId
      properties:
        idempotencyKey:
          $ref: '#/components/schemas/IdempotencyKey'
        clientEntityId:
          type: string
          format: uuid
          description: >-
            Optional child entity that should own the refund address. When
            omitted, the address is PSP-owned/shared.
          example: 7c1fb25a-f814-4c57-b06f-d5a25bfbf935
        paymentId:
          type: string
          format: uuid
          description: >-
            Original payment identifier. Recipient identity is derived from this
            payment's Travel Rule originator PII.
          example: 74fe686b-9142-43ab-9ba9-2e0c9b366d70
        chain:
          $ref: '#/components/schemas/Chain'
        address:
          $ref: '#/components/schemas/Address'
        addressTag:
          $ref: '#/components/schemas/AddressTag'
        metadata:
          $ref: '#/components/schemas/PaymentRefundAddressMetadata'
        ownership:
          $ref: '#/components/schemas/PaymentRefundAddressOwnership'
          description: >-
            Refund address ownership. `ownership.custody.vaspId` is required and
            must match the VASP recorded on the original payment.
    PaymentRefundAddress:
      type: object
      description: Refund address-book entry used as a crypto refund destination.
      properties:
        clientEntityId:
          type: string
          format: uuid
          description: Child entity that owns the refund address, when applicable.
          example: 7c1fb25a-f814-4c57-b06f-d5a25bfbf935
        id:
          $ref: '#/components/schemas/Id'
        chain:
          $ref: '#/components/schemas/Chain'
        address:
          $ref: '#/components/schemas/Address'
        addressTag:
          $ref: '#/components/schemas/AddressTag'
        metadata:
          $ref: '#/components/schemas/PaymentRefundAddressMetadata'
        identity:
          $ref: '#/components/schemas/PaymentRefundAddressIdentity'
        ownership:
          $ref: '#/components/schemas/PaymentRefundAddressOwnership'
        status:
          $ref: '#/components/schemas/PaymentRefundAddressStatus'
        createDate:
          $ref: '#/components/schemas/UtcTimestamp'
        updateDate:
          $ref: '#/components/schemas/UtcTimestamp'
    IdempotencyKey:
      type: string
      description: >-
        Universally unique identifier (UUID v4) idempotency key. This key is
        utilized to ensure exactly-once execution of mutating requests.
      format: uuid
      example: ba943ff1-ca16-49b2-ba55-1057e70ca5c7
    Chain:
      type: string
      description: >
        A blockchain that a given currency is available on.


        **Note:** Arc (`ARC`) is only available in the sandbox environment
        (`api-sandbox.circle.com`).
      enum:
        - ALGO
        - APTOS
        - ARB
        - ARC
        - AVAX
        - BASE
        - BTC
        - CELO
        - CODEX
        - ETH
        - HBAR
        - HYPEREVM
        - INK
        - LINEA
        - NEAR
        - NOBLE
        - OP
        - PLUME
        - PAH
        - POLY
        - SEI
        - SOL
        - SONIC
        - SUI
        - UNI
        - WORLDCHAIN
        - XLAYER
        - XDC
        - XLM
        - XRP
        - ZKS
        - ZKSYNC
    Address:
      type: string
      description: >
        An alphanumeric string representing a blockchain address. Formatting
        varies by blockchain.

        Be sure to preserve the exact formatting and capitalization of the
        address.  

        **Important:** For Ripple (XRP) addresses, only the classic address
        format is supported (for example,
        `rPEPPER7kfTD9w2To4CQk6UCfuHM9c6GDY`).  

        The `x-address` format is NOT supported currently (for example,
        `XV5sbjUmgPpvXv4ixFWZ5ptAYZ6PD2q1qM6owqNbug8W6KV`).
      example: '0x8381470ED67C3802402dbbFa0058E8871F017A6F'
    AddressTag:
      type: string
      description: >-
        The secondary identifier for a blockchain address. An example of this is
        the memo field on the Stellar network, which can be text, id, or hash
        format.
      nullable: true
      example: '123456789'
    PaymentRefundAddressMetadata:
      type: object
      description: Metadata for a refund address.
      properties:
        nickname:
          type: string
          example: Refund recipient
        email:
          type: string
          example: satoshi@example.com
        bns:
          type: string
          example: sample.circle
        lei:
          type: string
          example: 529900T8BM49AURSDO55
    PaymentRefundAddressOwnership:
      type: object
      required:
        - custody
      properties:
        type:
          type: string
          description: Ownership type for the refund address.
          enum:
            - third_party
          example: third_party
        custody:
          $ref: '#/components/schemas/PaymentRefundAddressCustody'
    Id:
      type: string
      description: Unique system generated identifier for the entity.
      format: uuid
      example: b8627ae8-732b-4d25-b947-1df8f4007a29
    PaymentRefundAddressIdentity:
      type: object
      description: >-
        Recipient identity derived from the original payment's Travel Rule
        originator PII. Do not provide this object when creating a refund
        address.
      properties:
        type:
          type: string
          enum:
            - individual
            - business
          example: individual
        firstName:
          type: string
          example: John
        lastName:
          type: string
          example: Doe
        businessName:
          type: string
          example: Example Trading Pte. Ltd.
        individual:
          $ref: '#/components/schemas/PaymentRefundAddressIndividualIdentity'
        business:
          $ref: '#/components/schemas/PaymentRefundAddressBusinessIdentity'
    PaymentRefundAddressStatus:
      type: string
      description: Refund address status.
      enum:
        - pending
        - pending_verification
        - pending_additional_information
        - pending_owner_information
        - pending_beneficiary_information
        - denied
        - inactive
        - verification_succeeded
        - active
        - on_hold
        - failed
        - disabled
      example: pending
    UtcTimestamp:
      type: string
      description: ISO-8601 UTC date/time format.
      example: '2020-04-10T02:13:30.000Z'
    PaymentRefundAddressCustody:
      type: object
      required:
        - type
        - vaspId
      properties:
        type:
          type: string
          description: Custody type for the refund address.
          enum:
            - hosted
          example: hosted
        vaspId:
          type: string
          format: uuid
          description: >-
            Hosted VASP identifier. Must match the VASP associated with the
            original payment sender.
          example: 581b9b20-28e1-464d-a257-e408733d0857
    PaymentRefundAddressIndividualIdentity:
      type: object
      properties:
        dateOfBirth:
          type: string
          example: '1990-11-29'
        nationality:
          type: string
          example: US
        addressLine1:
          type: string
          example: 123 Main St.
        addressLine2:
          type: string
          example: Apt 4B
        city:
          type: string
          example: Boston
        district:
          type: string
          example: MA
        postalCode:
          type: string
          example: '02110'
        country:
          type: string
          example: US
        governmentIssuedId:
          type: string
          example: A1234567
    PaymentRefundAddressBusinessIdentity:
      type: object
      properties:
        addressLine1:
          type: string
          example: 1 Raffles Place
        addressLine2:
          type: string
          example: '#10-01'
        city:
          type: string
          example: Singapore
        district:
          type: string
          example: SG
        postalCode:
          type: string
          example: 48616
        country:
          type: string
          example: SG
        businessRegistrationNumber:
          type: string
          example: 202000001A
        dateOfIncorporation:
          type: string
          example: '2020-01-15'
        countryOfIncorporation:
          type: string
          example: SG
        businessIdentificationNumber:
          type: string
          example: 202000001A
  headers:
    XRequestId:
      description: >-
        Universally unique identifier (UUID v4) for the request. Helpful for
        identifying a request when communicating with Circle support.
      schema:
        type: string
        format: uuid
        example: 2adba88e-9d63-44bc-b975-9b6ae3440dde
  responses:
    BadRequest:
      description: The request cannot be processed due to a client error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            type: object
            title: BadRequest
            required:
              - code
              - message
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: Something went wrong.
            example:
              code: 400
              message: Bad request.
          examples:
            response:
              value:
                code: 400
                message: Bad request.
    NotAuthorized:
      description: >-
        The request has not been applied because it lacks valid authentication
        credentials.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            type: object
            title: NotAuthorized
            required:
              - code
              - message
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: Something went wrong.
            example:
              code: 401
              message: Malformed authorization.
          examples:
            response:
              value:
                code: 401
                message: Malformed authorization.
    Forbidden:
      description: >-
        The request provides authentication, but the authenticated user does not
        possess sufficient permissions for accessing this resource.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            type: object
            title: Forbidden
            required:
              - code
              - message
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: Something went wrong.
            example:
              code: 3
              message: Forbidden
          examples:
            response:
              value:
                code: 3
                message: Forbidden
    InternalServerError:
      description: Unexpected server error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            type: object
            title: InternalServerError
            required:
              - code
              - message
            properties:
              code:
                type: integer
                example: 400
              message:
                type: string
                example: Something went wrong.
            example:
              code: 500
              message: Internal server error.
          examples:
            response:
              value:
                code: 500
                message: Internal server error.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````