> ## Documentation Index > Fetch the complete documentation index at: https://developer.utgl.io/llms.txt > Use this file to discover all available pages before exploring further. # Authorize Purchase Transaction > **Authorizes Purchase Transaction.** Provide **`cardId`**, **`amount`**, **`currency`**, **`description`**, and **`otpToken`** within the payload. On success, funds will be held and a **`transactionId`** is returned. ## OpenAPI ````yaml /merchant/partner-connect/partner-connect.yaml post /partner-connect/transactions/purchase openapi: 3.0.2 info: title: Partner Connect API Reference description: > # Partner Connect API Documentation Welcome to the Partner Connect API documentation. This API allows external partners (merchants, service providers) to integrate with our card services for binding customer cards and processing transactions. ## Key Features: - Secure Card Binding: Link customer payment cards to your system securely. - Transaction Processing: Authorize, capture, void, and refund payments using bound cards. ## Notes for API Integration - **Authentication:** Requests must be authenticated using either HTTP Basic Auth or Bearer Token (JWT), as specified in the `securitySchemes`. - **Error Handling:** The API uses standard HTTP status codes. Specific error details are provided in the response body with `code` and `message` fields. Refer to the `components/schemas/ErrorPartnerConnect...` definitions and the specific endpoint `responses` for details on possible errors. - **Idempotency:** Where applicable (e.g., transaction initiation), consider implementing idempotency checks on your side using unique request identifiers if needed, although the API itself may handle idempotency for certain operations like binding initiation. version: '1.0' servers: - url: tbc security: - Basic: [] - Bearer: [] tags: - name: Partner Connect description: >- Endpoints for integrating partner systems with card services, including card binding and transaction processing. paths: /partner-connect/transactions/purchase: post: tags: - Transactions summary: Authorize Purchase Transaction description: > **Authorizes Purchase Transaction.** Provide **`cardId`**, **`amount`**, **`currency`**, **`description`**, and **`otpToken`** within the payload. On success, funds will be held and a **`transactionId`** is returned. requestBody: required: true description: >- Requires the `cardId`, transaction details (`amount`, `currency`, `description`), and the `otpToken` in the request body. content: application/json: schema: type: object required: - cardId - amount - currency - description - otpToken properties: cardId: type: string format: uuid description: Identifier of the card to be used for the transaction. amount: type: number format: float minimum: 0.01 multipleOf: 0.01 description: Requested transaction amount. example: 100 currency: description: Currency code (ISO 4217) of the transaction amount. type: string minLength: 3 maxLength: 3 example: USD description: type: string description: Description of the transaction (e.g., store details). example: 'Order #123' otpToken: type: string description: The verification code for authorizing the transaction. example: '123456' responses: '200': description: >- Transaction successfully authorized. Funds are locked on the cardholder's account, awaiting capture or release. The response contains the `transactionId` and authorization details. content: application/json: schema: type: object properties: transactionId: description: >- A unique identifier (UUID) for this specific transaction authorization. **Store this ID securely**, as it's required to capture or release the funds. type: string format: uuid status: $ref: '#/components/schemas/PartnerConnectTransactionStatus' description: >- The current status of the transaction, which will be `locked` after successful authorization. amountAuthorized: description: >- The actual amount authorized for the transaction, formatted to 2 decimal places. type: number format: float minimum: 0.01 multipleOf: 0.01 example: 100 currency: description: Currency code (ISO 4217) of the authorized amount. type: string minLength: 3 maxLength: 3 example: USD authorizationExpiry: description: >- The timestamp (ISO 8601 format) when this authorization will automatically expire if it is not captured or released. type: string format: date-time pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}(?::?\d{2})?)$ cardId: description: >- The unique identifier (UUID) assigned to the successfully bound card. **Store this `cardId` securely**, as it is required to reference this card in all subsequent transaction requests (`/verify`, `/purchase`, etc.). type: string format: uuid refId: description: >- A unique transaction identifier provided for the client’s reference. It can be used to track or correlate transactions type: string example: CT6KQDDEC2 required: - transactionId - status - amountAuthorized - currency - authorizationExpiry '400': description: >- Bad Request. The provided `cardId` is invalid (`INVALID_CARD_ID`), amount/currency is invalid, OTP format is wrong, or decryption failed. content: application/json: schema: $ref: '#/components/schemas/ErrorPartnerConnectInvalidCard' '406': description: >- Purchase Authorization Failed. The transaction could not be authorized due to issues like insufficient funds (`INSUFFICIENT_FUNDS`), decline by the bank/network (`PURCHASE_DECLINED`), or an invalid OTP (`INVALID_CODE`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorPartnerConnectInsufficientFund' - $ref: '#/components/schemas/ErrorPartnerConnectPurchaseDeclined' - $ref: '#/components/schemas/ErrorPartnerConnectInvalidCode' '500': $ref: '#/components/responses/InternalServerError' components: schemas: PartnerConnectTransactionStatus: type: string enum: - locked - captured - void - refunded description: > Enum representing the lifecycle status of a Partner Connect transaction: * `locked` - An authorization request was successful. Funds are reserved on the cardholder's account but not yet transferred. This transaction can be captured or released (voided). * `captured` - The previously locked funds have been successfully transferred from the cardholder to the merchant. This transaction can potentially be refunded. * `void` - The previously locked funds have been released back to the cardholder before capture. The authorization is cancelled. * `refunded` - Funds for a previously captured transaction have been returned to the cardholder. ErrorPartnerConnectInvalidCard: description: | The provided **Card ID** is either invalid or not bound. Ensure it is a valid **UUID** linked to a bound card. type: object properties: code: type: string description: Error code, i.e. `INVALID_CARD_ID`. default: INVALID_CARD_ID message: type: string description: Human-readable error explanation. default: Invalid Card ID. ErrorPartnerConnectInsufficientFund: description: | The card associated with this **Card ID** has **insufficient funds**. Please verify the card balance or try an alternative payment method. type: object properties: code: type: string description: Error code, i.e. `INSUFFICIENT_FUNDS`. default: INSUFFICIENT_FUNDS message: type: string description: Human-readable error explanation. default: >- The card associated with this Card ID has insufficient funds to authorize the purchase transaction. ErrorPartnerConnectPurchaseDeclined: description: | The purchase transaction was declined by the bank or payment network. Consider using a different payment method or contacting the card issuer. type: object properties: code: type: string description: Error code, i.e. `PURCHASE_DECLINED`. default: PURCHASE_DECLINED message: type: string description: Human-readable error explanation. default: >- The purchase transaction has been declined by the payment network or issuing bank. Advise the customer to use an alternative payment method or contact their bank. ErrorPartnerConnectInvalidCode: description: | The provided **verification code** is incorrect or has expired. Reinitiate the process or verify the entered code. type: object properties: code: type: string default: INVALID_CODE description: Error code, i.e. `INVALID_CODE`. message: type: string default: >- The verification code provided is incorrect or has expired. Please check the code or re-initiate the process (binding or purchase verification) to receive a new code. description: Human-readable error explanation. responses: InternalServerError: description: >- Internal Server Error. A server error occurred. Please try again later; if the problem persists, contact support. content: application/json: schema: type: object properties: code: type: string description: Error code, i.e. `INTERNAL_SERVER_ERROR`. default: INTERNAL_SERVER_ERROR message: type: string description: A brief message indicating a server-side error. default: Your request could not be processed due to a server error. securitySchemes: Basic: type: http scheme: basic Bearer: type: http scheme: bearer bearerFormat: JWT ````