> ## Documentation Index > Fetch the complete documentation index at: https://docs.afriex.com/llms.txt > Use this file to discover all available pages before exploring further. # Update Payment Batch > Replaces the batch's name and funding method. Send both: the batch is updated whole. Requires the `PAYMENT_METHOD.CREATE` key permission. Replaces the batch's name and funding method. Send both fields, the batch is updated whole. Requires the `PAYMENT_METHOD.CREATE` key permission. ## OpenAPI ````yaml PATCH /api/v1/payment-batch/{batchId} openapi: 3.1.0 info: title: Afriex Business API version: 1.0.13 description: >- Welcome to the Afriex Business API. This API allows you to manage customers, process payments, handle payouts, and receive real-time notifications via webhooks. For detailed guidance on authentication, pagination, error handling, and webhooks, please refer to the [dedicated guides](https://docs.afriex.com) in the top bar. The guide provides a step-by-step instructions to help you integrate seamlessly. ## Testing in sandbox Send requests to `https://sandbox.api.afriex.com` with a sandbox API key. No real money moves. Deposits, payouts and virtual accounts can be tested on every payment method and currency your business supports. **When transactions complete.** A sandbox deposit or payout completes on its own about 5 minutes after it is created, and your webhook receives the final status, exactly as in production. To complete one sooner: - Include `SIMULATE_INSTANT` anywhere in `meta.reference` when you create it, and it completes in about 30 seconds. - Or call `POST /api/v1/transaction/{transactionId}/simulate` with `{"outcome": "success"}` or `{"outcome": "failed"}` to complete it now. **Choosing an outcome.** The last four digits of the account number, the phone number or the card number decide what happens. A payment method with none of these (an email or a wallet address) succeeds unless you complete it with `/simulate`: | Ends in | Payout | Mobile money deposit | Card deposit | | --- | --- | --- | --- | | anything else | Succeeds | Succeeds | Succeeds | | `0001` | Fails; your balance is refunded | Fails | Fails | | `0002` | Succeeds | Waits for a one-time password (see below) | Succeeds | | `0003` | Stays pending until you call `/simulate` | Stays pending until you call `/simulate` | Stays pending until you call `/simulate` | | `0004` | Account name lookup (`GET /api/v1/payment-method/resolve`) fails | Succeeds | Succeeds | | `0005` | Declined immediately | Declined immediately | Declined immediately | A phone number must still be a valid mobile number for its country, so keep the country prefix and change only the last digits, for example `+254712340002` in Kenya. Account name lookups return `Sandbox Test Account`. **One-time passwords.** A mobile money deposit from a wallet ending in `0002` returns `CUSTOMER_ACTION_REQUIRED`. Complete it with `POST /api/v1/transaction/{transactionId}/authorize` and the OTP `123456`; any other OTP returns `OTP_INCORRECT`. The deposit then completes as above. **Virtual accounts.** Sandbox virtual accounts receive no money on their own. Pay into one with `POST /api/v1/payment-method/virtual-account/simulate-transfer`. **Cards.** Collect the card as you would in production, using a test card number whose last four digits choose the outcome. **Balances and webhooks.** Fund your sandbox balance with `POST /api/v1/org/balance/topup`, and send yourself a sample webhook with `POST /api/v1/webhooks/trigger`. termsOfService: https://www.afriex.com/terms-and-condition contact: name: Afriex API Support email: support@afriex.com url: https://docs.afriex.com license: name: Proprietary url: https://www.afriex.com/terms-and-condition servers: - url: https://sandbox.api.afriex.com description: Staging Base URL - url: https://api.afriex.com description: Production Base URL security: - ApiKey: [] tags: - name: Customers description: Create and manage your customers. - name: Payment Methods description: Register and resolve customer payout and collection methods. - name: Transactions description: Create and track deposits, withdrawals, and swaps. - name: Balance description: View and top up your business wallet balances. - name: Rates description: Fetch real-time exchange rates. - name: Checkout Sessions description: Create hosted checkout sessions. - name: Webhooks description: Webhook event payloads and sandbox webhook testing. - name: Media description: Generate presigned URLs for secure file uploads. - name: Payment Batches description: >- Manage payment batches, their recipients and their runs. Where payload signing is enabled for your business, sign the JSON of the request body for POST and PATCH routes that take one. For GET routes with `page` and `limit`, and for the withdraw route, sign the query parameters as the server reads them, with defaults applied: a list call with no parameters signs `{"limit":100,"page":0}` and a withdraw with no `sessionId` signs `{}`. For the remaining routes (get, delete and remove-recipient) sign the path parameters, e.g. `{"batchId":"..."}`. paths: /api/v1/payment-batch/{batchId}: parameters: - $ref: '#/components/parameters/x-api-version' - $ref: '#/components/parameters/x-api-signature' - $ref: '#/components/parameters/paymentBatchId' patch: tags: - Payment Batches summary: Update a payment batch description: >- Replaces the batch's name and funding method. Send both: the batch is updated whole. Requires the `PAYMENT_METHOD.CREATE` key permission. operationId: updatePaymentBatch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PaymentBatchRequest' responses: '200': description: The updated batch content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PaymentBatch' '400': $ref: '#/components/responses/PaymentBatchBadRequest' '401': $ref: '#/components/responses/PaymentBatchUnauthorized' '404': $ref: '#/components/responses/PaymentBatchNotFound' components: parameters: x-api-version: name: x-api-version in: header required: false description: >- API version in ISO 8601 format. The only supported version is `2026-05-18`, which is also the default when the header is omitted. Any other value is rejected with a `400 Bad Request`. schema: type: string x-api-signature: name: x-api-signature in: header required: false description: >- Signature of the request payload, used for request authentication where payload signing is enabled for your business. schema: type: string paymentBatchId: name: batchId in: path required: true description: Id of a batch belonging to the calling business. schema: type: string schemas: PaymentBatchRequest: type: object required: - name - sourcePaymentMethod additionalProperties: false properties: name: type: string description: A label for the batch. sourcePaymentMethod: type: object description: >- The wallet the batch is funded from. Every payout is converted from this currency. Other keys are ignored and not stored. required: - currencyCode properties: channel: type: string enum: - WALLET default: WALLET currencyCode: type: string example: USD PaymentBatch: type: object description: A payment batch, including the method payouts are funded from. properties: id: type: string name: type: string sourcePaymentMethod: type: object description: >- The payment method the batch is funded from, as the payment-method endpoints return it. Round-tripped whole on update. meta: type: object properties: memberCount: type: integer ErrorResponse: type: object properties: code: type: string description: Machine-readable error code. error: type: string description: Human-readable error message. details: $ref: '#/components/schemas/ErrorDetails' ErrorDetails: type: object properties: errorMessage: type: string description: Detailed/technical error message. friendlyMessage: type: string description: User-facing error message safe to display. data: type: object description: >- Optional caller-safe context for the error. On a customer-create uniqueness conflict (EMAIL_ALREADY_EXISTS / PHONE_NUMBER_ALREADY_EXISTS) this carries the existing customer's id, so you can adopt it without a follow-up lookup. properties: customerId: type: string description: Id of the existing customer (on a create conflict). responses: PaymentBatchBadRequest: description: >- The request is invalid, or it came from an IP outside the business's whitelist or carried a bad payload signature. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' PaymentBatchUnauthorized: description: >- Missing or invalid API key, or a key without the permission this endpoint requires. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' PaymentBatchNotFound: description: No batch with this id belongs to the calling business. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: ApiKey: type: apiKey in: header name: x-api-key description: >- Static business API key issued from the dashboard. A business can provision **multiple API keys**, each scoped to a configurable set of **permissions** (e.g. read transactions, create deposits, etc). Permissions are chosen per key at creation time in the dashboard and may be revoked by deleting the key. Manage your keys and their permissions under **Developer → API keys** in the dashboard. A request whose key does not carry the permission the target endpoint requires is rejected with `401 Unauthorized`, the same response an unrecognised, malformed, revoked or disabled key returns. The API does not distinguish the two cases on the wire. See the [Permissions reference](https://docs.afriex.com/api-reference/permissions) for the permission each endpoint requires. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.