> ## Documentation Index > Fetch the complete documentation index at: https://docs.busha.io/llms.txt > Use this file to discover all available pages before exploring further. # Finalize a payment request > Finalize a payment request ## OpenAPI ````yaml https://raw.githubusercontent.com/bushaHQ/openapi/refs/heads/main/openapi-spec.yaml post /v1/payments/requests/{id}/finalize openapi: 3.0.0 info: title: Busha API contact: email: developers@busha.co description: > ## Introduction The **Busha API** is designed to provide businesses with tools for borderless financial transactions and operations, enabling modern, global money management. It serves as the backbone for facilitating: - Creation and management of multi-currency balances - Retrieval of real-time cryptocurrency rates - Substantial data insights for business owners Whether you’re a product-driven fintech or a developer building integrations, this API significantly accelerates implementation while reducing financial complexities. For detailed guides on API integration, visit our [official documentation](). ## Authentication All API requests require a **Bearer Token** for authentication, passed in the `Authorization` header. Your authorization value is a base64 encoded value of your api key and your secret key. You can obtain API tokens via your Busha user or business account. Authentication is mandatory to ensure secure and authorized interactions with the API. The API keys from the dashboard provides a base64 encoding of the your authorization tokens. Your generated Key should look like this: `VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=` Example Header: ``` curl Authorization: Bearer VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW= ``` ## Error Handling #Standardized error responses ensure predictable interactions. Errors are detailed for easy debugging and understanding: | **Error Code** | **HTTP Status Code** | **Description** | | --- | --- | --- | | `bad_request` | 400 | Invalid input or malformed request | | `unauthorized` | 401 | Invalid or missing authentication | | `not_found` | 404 | Resource not found | | `service_unavailable` | 503 | Server error | Basic Error Example: ``` json { "error": { "name": "bad_request", "message": "Invalid input data" } } ``` Schema Error Body Example: ``` json { "error": { "name": "bad_request", "message": "Invalid input data" }, "schema": { "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification", "fix": "Ensure that the object being submitted, matches the schema correctly" } } ``` Field Error Body Example: ``` json { "error": { "name": "bad_request", "message": "Invalid input data" }, "fields": { "field1": [ { "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification", }, ], "field2": [ { "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification", } ], } } ``` ## Pagination Pagination uses cursors provided as: The API supports **cursor-based pagination** for endpoints with large datasets. Pagination uses a `next_cursor` and `previous_cursor` returned in the response. Example Response Format: ``` json { "current_entries_size": 10, "next_cursor": "base64_cursor_value", "previous_cursor": "base64_previous_cursor_value" } ``` ## Rate Limiting Rate limits determine how many API calls can be made in a rolling minute. This ensures fair and optimized use of system resources. The rate limits allowed by each resource will be provided with the header: ```curl x-rate-limit 100 ``` If this header does not exist, then the rate limit is set at a default 100 req/min Requests exceeding the allocated quota will receive a `429 Too Many Requests` response. ## Common Parameters Common parameters enhance consistency across endpoints: | **Parameter Name** | **Location** | **Description** | **Example** | | --- | --- | --- | --- | | `X-BU-PROFILE-ID` | Header | User profile identifier | `BUS_qwejinoiuiqw93ejjw` | | `id` | Path | Unique NanoID identifier | `dpt_jweqafajsndiun34fd` | | `cursor` | Query | Pagination cursor | `base64_cursor_string` | #### Paginated Response Example ``` json { "status": "success", "message": "Data retrieved", "pagination": { "next_cursor": "value_for_next_page", "current_entries_size": 20 }, "data": [...] } ``` version: 1.0.0 servers: - url: https://api.sandbox.busha.so description: Sandbox Environment - url: https://api.busha.io description: Production Environment security: [] tags: - name: Balances description: Handles account balances across different currencies. x-displayName: Balances - name: Bills description: Lorem Ipsum x-displayName: Bills - name: Cards description: Lorem Ipsum x-displayName: Cards - name: Cashback description: Main tag for cashback service endpoints x-displayName: Cashback - name: Currencies description: > Endpoints to manage supported currencies, their properties, and network details. x-displayName: Currencies - name: Customers x-internal: false description: Handle customer requests and responses x-displayName: Customers - name: Files description: Provides APIs to handle files upload x-displayName: Files - name: Mandate x-displayName: Mandate - name: Miscellaneous description: Provides auxiliary APIs to complement and enhance other services. x-displayName: Miscellaneous - name: News description: News article endpoints x-displayName: News - name: Pairs description: Access trading pair information and rates x-displayName: Pairs - name: PaymentLinks description: Payment Links x-displayName: PaymentLinks - name: PaymentRequests description: Payment request x-displayName: PaymentRequests - name: Pledges description: Customer-authorized pledge lifecycle APIs x-displayName: Pledges - name: PriceAlerts description: Price alert management endpoints x-displayName: PriceAlerts - name: Quotes description: Handle quotes requests and responses x-displayName: Quotes - name: Recipients x-displayName: Recipients - name: Transactions x-displayName: Transactions - name: Transfers x-displayName: Transfers - name: Widget description: Widget operations x-displayName: Widget paths: /v1/payments/requests/{id}/finalize: post: tags: - PaymentRequests summary: Finalize a payment request description: Finalize a payment request operationId: finalizePaymentRequest parameters: - $ref: '#/components/parameters/PathParamNanoID' - $ref: '#/components/parameters/ProfileHeader' requestBody: content: application/json: schema: $ref: '#/components/schemas/FinalizePaymentRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PaymentRequestResponse' 4XX: $ref: '#/components/responses/PaymentRequestError4XX' 5XX: $ref: '#/components/responses/PaymentRequestError5XX' security: - Auth: - transfers:write - api:write components: parameters: PathParamNanoID: in: path name: id required: true schema: type: string format: nanoid example: bus_123456789 x-oapi-codegen-extra-tags: validate: required|nanoid ProfileHeader: in: header name: X-BU-PROFILE-ID required: false description: User profile header schema: type: string example: BUS_YOK8tp5Zga01qOKEsqp07 schemas: FinalizePaymentRequest: type: object properties: code: type: string maxLength: 6 description: Optional auth code required for MFA PaymentRequestResponse: allOf: - $ref: '#/components/schemas/BaseSchema' - type: object required: - data properties: data: $ref: '#/components/schemas/PaymentRequest' BaseSchema: description: General response Values type: object required: - status - message properties: status: type: string x-order: 1 x-go-type: string enum: - success - error example: success message: type: string x-order: 2 example: message for success PaymentRequest: type: object required: - id - source_amount - source_currency - target_amount - target_currency - requested_amount - currency - rate - fees - reference - additional_info - merchant_info - status - type - created_at - updated_at - expires_at properties: id: allOf: - $ref: '#/components/schemas/NanoID' x-order: 1 type: allOf: - $ref: '#/components/schemas/PaymentRequestType' x-order: 2 status: allOf: - $ref: '#/components/schemas/PaymentRequestStatus' x-order: 3 source_amount: allOf: - $ref: '#/components/schemas/Decimal' x-order: 4 source_currency: allOf: - $ref: '#/components/schemas/Currency' x-order: 5 target_amount: allOf: - $ref: '#/components/schemas/Decimal' x-order: 6 target_currency: allOf: - $ref: '#/components/schemas/Currency' x-order: 7 requested_amount: allOf: - $ref: '#/components/schemas/Decimal' description: The amount requested by the merchant x-order: 8 currency: allOf: - $ref: '#/components/schemas/Currency' description: The currency it was requested in x-order: 9 rate: allOf: - $ref: '#/components/schemas/QuoteRate' x-order: 10 fees: type: array items: $ref: '#/components/schemas/Fee' x-order: 11 pay_in: allOf: - $ref: '#/components/schemas/PaymentObj' x-order: 12 two_step: allOf: - $ref: '#/components/schemas/TwoStep' x-order: 13 reference: type: string x-order: 14 merchant_reference: type: string x-order: 15 additional_info: allOf: - $ref: '#/components/schemas/AdditionalInfo' x-order: 16 merchant_info: allOf: - $ref: '#/components/schemas/MerchantInfo' x-order: 17 source: type: string description: The source of the payment request x-order: 18 source_id: type: string description: The source id of the payment request x-order: 19 timeline: allOf: - $ref: '#/components/schemas/TransferTimeline' x-order: 20 created_at: type: string format: date-time example: '2023-10-15T12:15:30Z' x-order: 21 updated_at: type: string format: date-time example: '2023-10-15T12:15:30Z' x-order: 22 expires_at: type: string format: date-time example: '2023-10-15T12:15:30Z' x-order: 23 quote_rate: allOf: - $ref: '#/components/schemas/QuoteRate' x-order: 24 description: >- This shows the rate used to derive the amount when quote_currency is provided. ErrorResponse: type: object required: - error properties: error: type: object required: - name - message properties: name: type: string x-order: 40 example: bad_request message: type: string example: Invalid Request fields: type: object schema: type: array items: type: object example: error: name: bad_request message: Invalid Request NanoID: type: string x-order: 2 example: bus_123456789 format: nanoid description: A valid id x-oapi-codegen-extra-tags: validate: required|nanoid PaymentRequestType: type: string enum: - donation - checkout - invoice PaymentRequestStatus: type: string enum: - pending - expired - cancelled - completed - failed - multiple_deposits - under_payment - over_payment Decimal: type: string description: decimal value example: '100' x-go-type: decimal.Decimal x-go-type-import: path: github.com/shopspring/decimal name: decimal Currency: type: string x-order: 20 example: BTC format: string maxLength: 10 minLength: 1 description: A valid currency x-oapi-codegen-extra-tags: validate: required|min_len:1|max_len:10 filter: trim|upper QuoteRate: type: object properties: product: type: string example: BTCUSDT rate_explained: type: string example: 1 BTC = 1000 USDT source_currency: $ref: '#/components/schemas/Currency' target_currency: $ref: '#/components/schemas/Currency' rate: $ref: '#/components/schemas/Decimal' side: type: string enum: - buy - sell example: sell type: type: string enum: - FIXED example: FIXED Fee: type: object x-order: 40 required: - name - amount - type properties: name: type: string example: processing_fee amount: $ref: '#/components/schemas/AmountWithCurrency' converted_amount: $ref: '#/components/schemas/AmountWithCurrency' type: $ref: '#/components/schemas/FeeType' PaymentObj: allOf: - $ref: '#/components/schemas/PayOutObj' - type: object properties: profile_id: type: string example: profile-id-1234 memo: type: string example: address memo recipient_details: $ref: '#/components/schemas/RecipientDetails' blockchain_hash: type: string x-order: 16 example: 31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171 blockchain_url: type: string x-order: 16 example: >- https://explorer.com/tx/31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171 session_id: type: string x-order: 16 example: 31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171 from_address: type: string x-order: 16 example: 31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171 expires_at: type: string format: date-time example: '2023-10-15T12:15:30Z' TwoStep: type: object required: - type - message - resend_allowed x-order: 17 properties: type: type: string enum: - authenticator example: authenticator description: the type of two step verification required message: type: string example: Enter your 2FA code to continue resend_allowed: type: boolean example: false description: If the code can be resent AdditionalInfo: type: object required: - email properties: email: type: string format: email description: email address for the payment request phone_number: $ref: '#/components/schemas/PhoneField' name: $ref: '#/components/schemas/NameField' source: type: string description: The source of the payment request example: web MerchantInfo: type: object required: - name properties: name: type: string description: name of the business example: busha email: type: string format: email description: email of the business example: busha@me.com TransferTimeline: type: object required: - total_steps - current_step - transfer_status - events properties: total_steps: type: integer x-order: 1 current_step: type: integer x-order: 2 transfer_status: type: string x-order: 3 events: type: array items: $ref: '#/components/schemas/Timeline' AmountWithCurrency: type: object description: Amount with currency required: - amount - currency properties: amount: $ref: '#/components/schemas/Decimal' currency: $ref: '#/components/schemas/Currency' FeeType: type: string enum: - FIXED - PERCENTAGE - TIERED example: FIXED PayOutObj: type: object required: - type properties: type: type: string example: address description: | The payout type. NOTE: `sweep` is reserved for Busha Business dashboard sessions (master <-> sub-account internal transfers) and is rejected on public API-key requests. enum: - address - bank_transfer - mobile_money - paybill - till - payout_batch - balance - savings - direct_debit - sweep - internal recipient_id: type: string example: 64ae8c26ea1033204c805a8a description: > This represents the recipient ID, used for `mobile_money` and `bank_transfer` types. For `payout_batch`, this should contain the payout batch ID. address: type: string example: tb1qj4263506wyu8khrz2dwce0agk8lhyjgy269rxr description: > This could be the address, user email or username for type `address`. For type `sweep`, this is the email of the destination account. Required when the sender is the master (master -> sub); optional when the sender is a sub-account (the destination master is resolved automatically from the sub's parent business). For type `internal`, this is the destination Busha profile ID, destination email, or a public key that resolves to the owning business profile. network: type: string example: BTC description: > This specifies the blockchain network associated with the address receiving the payment, typically used with address type payouts. memo: type: string example: memo description: > This refers to the memo required for blockchain networks that mandate a memo for cryptocurrency transactions. narration: type: string example: Payment for services description: > A narration or description for the withdrawal. Required for USD bank transfer withdrawals. payment_invoice_url: type: string example: https://example.com/invoice.pdf description: > URL of the payment invoice or supporting document. Required for business account USD withdrawals and personal account USD withdrawals exceeding $10,000. RecipientDetails: type: object properties: account_name: type: string bank_name: type: string account_number: type: string country_code: type: string example: NG provider: type: string iban: type: string example: NG12345678901234567890 currency: type: string phone_number: type: string name: type: string email: type: string example: sbsbs@busha.co bank_code: type: string example: '100020' PhoneField: type: string example: '+2348012345678' format: phone description: A valid phone number. format `{{calling_code}}{{number}}` x-oapi-codegen-extra-tags: validate: phone filter: phone mapstructure: phone_number,omitempty NameField: type: string example: John description: A valid name Timeline: type: object required: - step - done - status - title - description properties: step: type: integer x-order: 1 example: 1 done: type: boolean x-order: 2 example: true status: type: string x-order: 3 enum: - pending - processing - funds_converted - funds_received - outgoing_payment_sent - funds_delivered - reverse_fund_conversion - failed - completed title: type: string x-order: 4 example: Transfer started description: type: string x-order: 5 example: Transfer started description: Waiting for payment timestamp: type: string x-order: 6 format: date-time example: '2023-10-15T12:15:30Z' responses: PaymentRequestError4XX: description: Default content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: default: $ref: '#/components/examples/DefaultError' not_found_error: $ref: '#/components/examples/NotFoundError' unauthorized_error: $ref: '#/components/examples/UnAuthorizedError' request_validation_error: $ref: '#/components/examples/RequestValidationError' schema_validation_error: $ref: '#/components/examples/SchemaValidationError' PaymentRequestError5XX: description: Default content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_server_error: $ref: '#/components/examples/InternalServerError' service_unavailable_error: $ref: '#/components/examples/ServiceUnavailableError' examples: DefaultError: description: Default error value: error: name: bad_request message: Invalid request NotFoundError: description: Not Found error value: error: name: resource_not_found message: Resource Not Found UnAuthorizedError: description: Unauthorized Error value: error: name: unauthorized message: Unauthorized request RequestValidationError: description: Request Validation error example value: error: name: request_validation message: Validation error fields: field1: - reason: One of target and source amount must be set field2: - reason: One of target and source amount must be set SchemaValidationError: description: Schema validation error example value: error: name: schema_validation message: Error Validating Requests schema: - reason: >- The request body is defined as an object. However, it does not meet the schema requirements of the specification fix: >- Ensure that the object being submitted, matches the schema correctly schema_validation_error: - 'minLength: got 3, want 12' InternalServerError: description: Internal Server Error value: error: name: internal_server_error message: Internal Server Error ServiceUnavailableError: description: Service Unavailable Error value: error: name: service_unavailable message: Service Unavailable securitySchemes: Auth: type: http scheme: bearer description: Bearer Authentication ````