> ## Documentation Index > Fetch the complete documentation index at: https://docs.infinityapp.in/llms.txt > Use this file to discover all available pages before exploring further. # Add a payee address > Sends a payee's bank details directly. The payee becomes `active` and can be paid straight away. - Global accounts only, and one address per payee. - Check the fields for each currency and rail with **List bank requirements**. - You're responsible for the details being right. We check the format and the bank provider checks the account, but a payout to a valid account that isn't the payee's can't be pulled back. ## OpenAPI ````yaml /api-reference/openapi.yaml post /payees/{id}/addresses openapi: 3.1.0 info: title: Infinity API version: v1 description: > Send cross-border payouts from your USD balance to payees' bank accounts. - **Hosts:** `https://sandbox-api.infinityapp.in/v1` for testing and `https://api.infinityapp.in/v1` for live money. - **Auth:** `Authorization: Bearer sk_test_…` on the sandbox, `sk_live_…` on live. - **JSON:** field names are snake_case. Amounts are decimal strings (`"500.00"`), currency codes are lowercase ISO 4217 (`"eur"`), countries are uppercase ISO 3166 alpha-2 (`"NL"`), and timestamps are ISO 8601 in UTC. - **Fixed shapes:** every documented response field is always present. It's `null` when there's no value, and `metadata` is `{}` when empty. - **Strict input:** an unknown field or query parameter gets a `400 unknown_parameter`, and a number where a string is expected gets a `400 type_mismatch`. - **Lists:** `limit` (1–100, default 20) and `starting_after` (the last id you saw). Responses are `{ "data": [...], "has_more": true }`, newest first. - **Idempotency:** the `Idempotency-Key` header is required on money-moving creates and optional on the others. The same key with the same body within 24 hours returns the original response. - **Request ID:** every response has a `Request-Id` header. Quote it to support. - **Rate limits:** 20 requests per second per key, with bursts up to 40. Over that gets a `429` with `Retry-After`. - **Versioning:** `/v1` only grows. New fields, endpoints, enum values, event types and error codes can be added at any time, so ignore what you don't recognise. servers: - url: https://sandbox-api.infinityapp.in/v1 description: Sandbox (sk_test_ keys) - url: https://api.infinityapp.in/v1 description: Live (sk_live_ keys) security: - apiKey: [] tags: - name: Account description: Your account profile and settings. - name: Wallets description: >- Funds held for you, one wallet per currency. Every payout names the wallet that pays for it. - name: Funding addresses description: Bank details you send money to, to fund your balance. - name: Deposits description: Money credited to your balance. - name: Currencies description: The currencies we support and which ones you can pay out in. - name: Exchange rates description: Indicative rates. A quote is the price. - name: Payees description: The people and businesses you pay. - name: Payee addresses description: >- A payee's bank account, sent by you instead of the payee filling in our hosted form. - name: Bank requirements description: The fields each currency and rail needs. - name: Quotes description: Price payouts before you send them. Nothing is saved. - name: Payouts description: Create 1 to 100 payouts in one call, then track, update or cancel them. - name: Batches description: The set of payouts created by one Create payouts call. - name: Webhook endpoints description: URLs we notify when something changes. - name: Events description: Every change from the last 30 days, to catch up on missed webhooks. paths: /payees/{id}/addresses: post: tags: - Payee addresses summary: Add a payee address description: > Sends a payee's bank details directly. The payee becomes `active` and can be paid straight away. - Global accounts only, and one address per payee. - Check the fields for each currency and rail with **List bank requirements**. - You're responsible for the details being right. We check the format and the bank provider checks the account, but a payout to a valid account that isn't the payee's can't be pulled back. operationId: createPayeeAddress parameters: - $ref: '#/components/parameters/PayeeId' - $ref: '#/components/parameters/IdempotencyKeyOptional' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePayeeAddressRequest' responses: '200': description: The new address. content: application/json: schema: $ref: '#/components/schemas/PayeeAddress' '400': description: > - `bank_details_invalid`: a field breaks a rail rule (`param` names it), or the bank provider rejected the details (`param: null`). - `invalid_payee_request`: the `currency` doesn't match the payee's. - `kyc_required`: INR payees enter their own details through hosted onboarding. - `missing_parameter`, `unknown_parameter`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: '`payee_not_found`.' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- `address_exists`: the payee already has an active address. `idempotency_key_reused`, `idempotency_key_in_use`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/RateLimited' 5XX: $ref: '#/components/responses/ServerError' components: parameters: PayeeId: name: id in: path required: true schema: type: string example: payee_c8pnahcrxqzd3z8d IdempotencyKeyOptional: name: Idempotency-Key in: header required: false description: Optional. Makes a retry safe, as on money-moving creates. schema: type: string maxLength: 255 schemas: CreatePayeeAddressRequest: type: object additionalProperties: false required: - type - currency - rail - owner_type - beneficiary_name - bank_name - account_number - beneficiary_address properties: type: type: string enum: - bank_account currency: type: string enum: - usd - eur - gbp description: Must match the payee's `currency` if it's already set. example: eur rail: type: string enum: - ach - wire - sepa - faster_payments description: >- `usd`: `ach` or `wire`, your choice. `eur`: `sepa`. `gbp`: `faster_payments`. example: sepa owner_type: type: string enum: - individual - business example: individual beneficiary_name: type: string maxLength: 35 description: >- The account holder's name. For `business` it's also the company name sent to the bank. example: Maria Lopez bank_name: type: string maxLength: 100 example: ABN AMRO account_number: type: string description: >- `ach` / `wire`: the account number. `sepa`: the IBAN (spaces are removed). `faster_payments`: 8 digits. example: NL91ABNA0417164300 routing_code: type: string description: >- `ach` / `wire`: the 9-digit routing number (required). `faster_payments`: the 6-digit sort code (required). `sepa`: the BIC, 8 or 11 characters (optional). account_type: type: string enum: - checking - savings description: On `ach` and `wire` only. beneficiary_address: $ref: '#/components/schemas/BeneficiaryAddressRequest' PayeeAddress: type: object required: - id - payee_id - type - currency - rail - owner_type - beneficiary_name - bank_name - account_number_last4 - routing_code - account_type - beneficiary_address - status - created_at properties: id: type: string example: address_7m3kq9xwd2hr5tna payee_id: type: string example: payee_c8pnahcrxqzd3z8d type: type: string enum: - bank_account currency: type: string enum: - usd - eur - gbp example: eur rail: type: string enum: - ach - wire - sepa - faster_payments description: Every payout to this address goes on this rail. example: sepa owner_type: type: string enum: - individual - business beneficiary_name: type: string example: Maria Lopez bank_name: type: string example: ABN AMRO account_number_last4: type: string example: '4300' routing_code: type: - string - 'null' description: >- The routing number, BIC or sort code. `null` for a SEPA account sent without a BIC. example: null account_type: type: - string - 'null' enum: - checking - savings - null description: On `ach` and `wire` only. example: null beneficiary_address: $ref: '#/components/schemas/BeneficiaryAddress' status: type: string enum: - active - inactive created_at: type: string format: date-time example: '2026-10-26T10:01:00Z' ErrorResponse: type: object required: - error properties: error: type: object required: - type - code - message - param - request_id - timestamp properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - api_error description: The class of error, from the HTTP status. code: type: string description: >- What went wrong. Branch on this. New codes can be added, so handle an unknown one by its HTTP status. example: invalid_payout_request message: type: string description: For a developer to read. It can change, so never parse it. example: amount has more than 2 decimals for eur. param: type: - string - 'null' description: >- The field at fault, with its path: `amount`, `items[3].payee_id`, `beneficiary_address.postal_code` or `Idempotency-Key`. example: amount request_id: type: string description: The same as the `Request-Id` header. example: req_4f4b2bjc4mamxuxm timestamp: type: string format: date-time example: '2026-10-29T10:00:00Z' BeneficiaryAddressRequest: type: object additionalProperties: false required: - line1 - city - country properties: line1: type: string maxLength: 35 description: Street and number. It must include a street number. example: Damrak 1 city: type: string example: Amsterdam state: type: string description: >- Required on `ach` and `wire`: an ISO 3166-2 subdivision code, such as `CA`. postal_code: type: string description: Required on `ach` and `wire`. example: '1012' country: type: string pattern: ^[A-Z]{2}$ description: ISO 3166 alpha-2 in uppercase. example: NL BeneficiaryAddress: type: object required: - line1 - city - state - postal_code - country properties: line1: type: string example: Damrak 1 city: type: string example: Amsterdam state: type: - string - 'null' example: null postal_code: type: - string - 'null' example: '1012' country: type: string example: NL responses: Unauthorized: description: >- `missing_authorization`, `invalid_api_key` (no such key, or it's revoked), `wrong_environment` (a test key on live, or a live key on the sandbox). headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: authentication_error code: wrong_environment message: This is a live key. Use it on api.infinityapp.in. param: null request_id: req_4f4b2bjc4mamxuxm timestamp: '2026-10-29T10:00:00Z' Forbidden: description: '`account_inactive`: the account behind this key isn''t active.' headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' RateLimited: description: >- `rate_limited`: over 20 requests per second for this key. Wait for `Retry-After` and try again. headers: Retry-After: $ref: '#/components/headers/RetryAfter' Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServerError: description: >- `internal_server_error` (500, our fault) or `service_unavailable` (503, something we depend on is down). Safe to retry with the same `Idempotency-Key`. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: RequestId: description: This call's id. Quote it to support. schema: type: string example: req_4f4b2bjc4mamxuxm RetryAfter: description: Seconds to wait before retrying. schema: type: integer example: 1 securitySchemes: apiKey: type: http scheme: bearer description: > Your secret key: `sk_test_…` on the sandbox host, `sk_live_…` on live. A key on the wrong host gets a `401 wrong_environment`. Keys are secret. Keep them on your server, never in a browser or app. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.