> ## Documentation Index > Fetch the complete documentation index at: https://docs.chip-in.asia/llms.txt > Use this file to discover all available pages before exploring further. # Capture a previously authorized payment Capture funds reserved for a Purchase (`status == hold`). You can place a `hold` (authenticate the payment) using `skip_capture == true` when creating the Purchase and ensuring your client submits the payment form. If this operation takes too long to be processed on the acquirer side - you will get a response with status code 200 and a Purchase object having `status` = `pending_capture` in body (you will receive a corresponding Webhook callback too for a `purchase.pending_capture` event). To be notified of a successful operation completion, please subscribe to `purchase.captured` callback event - it will deliver an updated Purchase with `status` = `paid`. If capture fails due to payment processing error, you will receive HTTP response code 400 with error code `purchase_capture_error`. In this case, to get more details about the error, you should perform a `GET /purchase/` request for the Purchase you tried to capture. In `transaction_data.attempts[]` array (newest element first) you'll find the corresponding attempt with error code and description in `.error` parameter. By default the full amount is captured, the `amount` body param is optional. ## OpenAPI ````yaml _openapi-chip-collect POST /purchases/{id}/capture/ openapi: 3.1.0 info: title: Public REST API version: v1 description: > All the endpoints below have a prefix of `https://gate.chip-in.asia/api/v1` (e.g. `POST https://gate.chip-in.asia/api/v1/purchases`). You will need your API key that you can obtain in the Developers section in your account. Please use this key as a bearer token in the Authorization header included in every request: `Authorization: Bearer `. You can generate and manage your API keys here :
https://portal.chip-in.asia/collect/developers/api-keys Your Brand ID is required for certain endpoints. You can find it here :
https://portal.chip-in.asia/collect/developers/brands Before starting the development, we recommend checking out the list of ready-to-go connectors to the popular platforms we’ve already built for you. It might save you some precious time if you use one of these to develop your project. Plugins: [WooCommerce](https://gate.chip-in.asia/apis/plugins/WooCommerce%20v3.5+), [Gravity Forms](https://gate.chip-in.asia/apis/plugins/Gravity%20Forms), [OpenCart](https://gate.chip-in.asia/apis/plugins/OpenCart%20v3.0+), [Magento](https://gate.chip-in.asia/apis/plugins/Magento%20v2.0+), [PrestaShop](https://gate.chip-in.asia/apis/plugins/PrestaShop%20v1.7+) Libraries: [PHP](https://gate.chip-in.asia/apis/libraries/PHP), [Java](https://gate.chip-in.asia/apis/libraries/Java), [C#](https://gate.chip-in.asia/apis/libraries/C%23), [Node.js](https://gate.chip-in.asia/apis/libraries/Node.js) SDKs: [iOS](https://gate.chip-in.asia/apis/sdks/iOS), [Android](https://gate.chip-in.asia/apis/sdks/Android) *** # Online Purchases ## Prebuilt payment flow — Redirect Redirect integration allows running payments using the prebuilt payment flow. To accept payments in your application or website via redirect, use `POST /purchases/` request to create the `Purchase` and receive the `checkout_url`. Redirect the customer to the `checkout_url` to enter their card details for processing. After the payment is processed, the system will redirect the customer back to your website (take note of `success_redirect`, `failure_redirect`). *You have three options to check payment status:* 1. Use `success_callback` parameter of the `Purchase` object. 2. Use `GET /purchases//` request. 3. Set up a Webhook using the Developers section of your account or use Webhook API to listen to `purchase.paid`, or `purchase.payment_failure` event on your server. Setting the `skip_capture` flag to `true` allows you to separate the authentication and payment execution steps, allowing you to reserve funds on the customer's card account for some time. This flag can also enable preauthorization capability, allowing you to save the card without a financial transaction, if possible. If the customer agrees to store his card for future purchases, there will be an option to pay with a single click next time. To enable this, create a `Client` object for each of your clients and provide `client_id` parameter value in your Purchase creation requests. To create a Purchase, you must specify the `Brand ID` and `API key`. You can find both in the Developers section of your account. ## Custom payment flow — Direct Post Direct post integration allows running payments through the custom payment flow. To accept payments in your application or website, use `POST /purchases/` request to create a `Purchase`. To capture customers card details use an HTML `
` hosted on your website with `method="POST"` and `action` pointing to the `direct_post_url` of the transaction. You will also need to fill the form with ``'s for the fields with card details. As a result, when a customer submits their card details, it will be posted straight to our system, allowing you to customize the checkout as you wish. At the same time, your PCI DSS requirement is only raised to Self-Assessment Questionnaire (SAQ A-EP), as your system doesn't receive or process card data. For more details, see the documentation on Purchase's `direct_post_url` field. ### Tokenization & recurring payments You can store card tokens and charge the respective cards without user interaction if the payment channel supports tokenization. When you pass `remember_card=on` to `direct_post_url`, the respective `Purchase`'s ID will serve as a card token. This initial `Purchase` will have the `is_recurring_token` field set to `true`. To charge the tokenized card once again, create a new Purchase and then call the `POST /purchases/{new_purchase_id}/charge/`. In the request body, provide `"recurring_token": "initial_purchase_id"`. When the request succeeds (response code `200`), the new Purchase will become paid. The token will be persisted in the Purchase's recurring_token field. Use `"recurring_token": "initial_purchase_id"` in all the upcoming `POST /purchases/{new_purchase_id}/charge/` requests. If you wish to delete the recurring token stored for the initial `Purchase`, use the `POST /purchases/{initial_purhcase_id}/delete_recurring_token/` request. Its `is_recurring_token` will reset to `false`. ## Testing Integration It’s possible to test-drive all checkouts using a test Purchase. For a successful payment, you can use the following card numbers: * 4444 3333 2222 1111 - non-3D Secure card * 5555 5555 5555 4444 - 3D Secure card For both cards, please use: * any cardholder name * any expiry larger or equal to the current month/year * CVC = 123 For a failed payment, please change the CVC or expiration date. When using a 3D Secure enrolled card in S2S checkout, an incorrect CVC will trigger an authorization failure on the S2S callback step (after the customer returns from test ACS). Using a wrong expiry date emulates data validation failure and results in immediate error before that step. *** # Callbacks Two methods for defining asynchronous callbacks are supported - `Purchase` success callbacks and webhooks. ## Purchase success callbacks `Purchase` success callbacks are defined by providing a target URL in the `success_callback` field on `Purchase` creation (see [POST /purchases/](#/Purchases/purchases_create)). The system will generate a callback when: * a `Purchase` with `skip_capture=false` is successfully paid; * a `Purchase` with `skip_capture=true` is successfully captured (see [POST /purchases/{id}/capture/](#/Purchases/purchases_capture)); * a `Purchase` is successfully paid using a recurring token (see [POST /purchases/{id}/charge/](#/Purchases/purchases_charge)); These callbacks pass a JSON-encoded `Purchase` as their payload. The payload represents a snapshot of the state of the `Purchase` when the event was created. The payload will include an `event_type` field to indicate which specific event (see [Event schema](#model-Event)) triggered the callback. The payload is signed using a company-wide key pair. You can obtain the public key with `GET /public_key/`. See the `Authentication` section below for more details. ## Webhooks For creating and modifying webhooks, see the Webhook [CRUD API specification](#operations-tag-Webhooks). `Webhook` callback payloads are signed using a dedicated key pair. You can obtain the public key from `Webhook.public_key`. See the [Authentication](#callback-auth) section below for more details. ## Delivery protocol When a callback is not successfully delivered (received by the target server and responded to with a 200 series HTTP response code), the system will make up to 8 additional attempts at exponentially increasing intervals between attempts. No further delivery attempts will be made if the callback is not successfully delivered 36 hours after triggering. Please note that due to the asynchronous nature of network requests, it is possible for a callback delivery confirmation (HTTP response with a 200 series status code) to not properly arrive from the callback's target server. Therefore it is possible in case of severe network faults for the target server to receive a callback, respond to it with a 200 series HTTP status code and then receive the same callback after an interval. Callback deliveries are guaranteed to be sequential to events triggered on their source objects. For example, when registering webhooks for both the `purchase.created` and `purchase.paid` events, there will be no `purchase.paid` callbacks for this `Purchase` until all `purchase.created` callbacks for this `Purchase` are successfully delivered. ## Authentication Payloads are signed using asymmetric A.K.A. public-key cryptography to guarantee the authenticity of delivered callbacks. Each callback delivery request includes an X-Signature header field. This field contains a base64-encoded RSA PKCS#1 v1.5 signature of the SHA256 digest of the request body buffer. You can obtain the public key for `Webhook` authentication from `Webhook.public_key` of the corresponding `Webhook`. You can obtain the public key for success callback authentication from [GET /public_key/](#operations-Public_Key-public_key). Please note the provider is not responsible for any financial losses incurred due to not implementing payload signature verification. servers: - url: https://gate.chip-in.asia/api/v1 security: - bearerAuth: [] paths: /purchases/{id}/capture/: parameters: - $ref: '#/components/parameters/id' post: tags: - Purchases summary: Capture a previously authorized payment operationId: purchases_capture requestBody: required: false content: application/json: schema: properties: amount: type: integer description: >- Amount to be captured. Used to perform partial captures. Remainder will be automatically released. responses: '200': $ref: '#/components/responses/Purchase' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' security: - bearerAuth: [] components: parameters: id: name: id required: true in: path description: Object ID (UUID) schema: type: string format: uuid responses: '400': description: Invalid data submitted or request processing error content: application/json: schema: type: object example: | { "__all__": { "message": "descriptive error message", "code": "error_code" } } '404': description: No such object Purchase: description: OK content: application/json: schema: $ref: '#/components/schemas/Purchase' schemas: Purchase: description: >- Record of a single purchase operation, either a transaction originating from e-commerce integration or invoice sent. Has a status attribute, e.g. can be `created`, `paid` or `refunded`. required: - client - purchase - brand_id properties: client: description: Either this or `.client_id` is required. allOf: - $ref: '#/components/schemas/ClientDetails' purchase: $ref: '#/components/schemas/PurchaseDetails' payment: nullable: true allOf: - $ref: '#/components/schemas/PaymentDetails' issuer_details: allOf: - $ref: '#/components/schemas/IssuerDetails' transaction_data: type: object description: >- Payment method-specific, read-only transaction data. Will contain information about all the transaction attempts and possible errors, if available. properties: payment_method: type: string description: >- Payment method used if Purchase was paid, blank string otherwise. flow: $ref: '#/components/schemas/TransactionFlow' processing_tx_id: type: string description: ID of the transaction in the processing system. extra: type: object description: >- Extra data associated with selected payment method if Purchase was paid, empty object otherwise. Dataset depends on payment method. E.g. for card payment methods like `visa` or `mastercard` it will contain properties `masked_pan: string`, `three_d_secure: boolean`, `expiry_month: int`, `expiry_year: int` and `cardholder_name: string`. country: type: string description: >- Country code (in the ISO 3166-1 alpha-2 format e.g. 'GB') where payment tool used originates (e.g. in case of card payments, the card issuing country). Will be blank if Purchase was not paid or country could not be detected. attempts: type: array description: >- Will contain information about all the payment attempts made and errors encountered, if any. items: type: object properties: type: type: string description: Type of action attempted enum: - execute - authorize - release - capture - recurring_execute - delete_recurring_token - refund successful: type: boolean description: >- If this attempt was successful or not. For `false`, `error` of this attempt will be not null. payment_method: type: string description: Payment method used for this attempt. extra: type: object description: >- Extra data associated with selected payment method. Dataset depends on payment method. E.g. for card payment methods like `visa` or `mastercard` it will contain properties `masked_pan: string`, `three_d_secure: boolean`, `expiry_month: int`, `expiry_year: int` and `cardholder_name: string`. country: type: string description: >- Country code (in the ISO 3166-1 alpha-2 format e.g. 'GB') where payment tool used originates (e.g. in case of card payments, the card issuing country). Will be blank if country could not be detected. client_ip: type: string format: IP description: IP the paying client made this attempt from, if available. processing_time: description: >- Time (if possible, fetched from the remot processing system) this attempt happened at. allOf: - $ref: '#/components/schemas/UnixTimestamp' error: type: object nullable: true description: >- Code and description of the error encountered. Not-null if `successful` parameter of this attempt is `false`. properties: code: type: string description: >- Available error codes: --- `unknown_payment_method`: Unknown payment method --- `invalid_card_number`: Invalid card number --- `invalid_expires`: Invalid expires --- `no_matching_terminal`: No matching terminal --- `blacklisted_tx`: Blacklisted transaction: blocked (general) --- `timeout_3ds_enrollment_check`: 3DS enrollment check timeout --- `timeout_acquirer_status_check`: Timeout checking payment status with acquirer --- `validation_card_details_missing`: Card data field values are missing from request --- `validation_cvc_not_provided`: `cvc` field not provided --- `validation_cardholder_name_not_provided`: `cardholder_name` field not provided --- `validation_card_number_not_provided`: `card_number` field not provided --- `validation_expires_not_provided`: `expires` field not provided --- `validation_cvc_too_long`: `cvc` is too long --- `validation_cardholder_name_too_long`: `cardholder_name` is too long --- `validation_card_number_too_long`: `card_number` is too long --- `validation_expires_too_long`: `expires` is too long --- `validation_cvc_invalid`: `cvc` is invalid --- `validation_cardholder_name_invalid`: `cardholder_name` is too long or invalid --- `validation_card_number_invalid`: `card_number` is invalid --- `validation_expires_invalid`: `expires` is invalid --- `acquirer_connection_error`: Acquirer connection error --- `blacklisted_tx_issuing_country`: Blacklisted transaction: issuing country --- `s2s_not_supported`: Server-to-server flow not supported by processing --- `timeout`: Operation timeout --- `general_transaction_error`: Unrecognized transaction error --- `antifraud_general`: Decline, fraud --- `acquirer_internal_error`: Acquirer internal error --- `exceeds_frequency_limit`: Exceeds frequency limit --- `insufficient_funds`: Insufficient funds --- `purchase_already_paid_for`: Purchase is already paid for --- `issuer_not_available`: Issuer Not Available --- `3ds_authentication_failed`: 3DS authentication failed --- `do_not_honour`: Do not honour (the transaction was declined by the Issuer without definition or reason). --- `exceeds_withdrawal_limit`: Exceeds withdrawal limit --- `exceeded_account_limit`: Exceeded account limit --- `expired_card`: Expired card --- `blacklisted_tx_risk_score`: Blacklisted transaction: risk score --- `transaction_not_supported_or_not_valid_for_card`: The transaction request presented is not supported or is not valid for the card number presented. --- `exceeded_acquirer_refund_amount`: Exceeded refundable amount defined by acquirer --- `transaction_not_permitted_on_terminal`: Transaction not permitted on terminal (this card does not support the type of transaction requested). --- `acquirer_configuration_error`: Acquirer configuration error --- `transaction_not_permitted_to_cardholder`: Transaction not permitted to cardholder --- `invalid_issuer_number`: No such issuer (the Issuer number is not valid). --- `restricted_card`: Restricted card --- `merchant_response_timeout`: Timeout of merchant response exceeded --- `reconcile_error`: Reconcilation error --- `lost_card`: Lost card --- `stolen_card`: Stolen card --- `invalid_amount`: Invalid amount --- `re_enter_transaction`: Re enter transaction --- `security_violation`: Security violation --- `partial_forbidden`: Intervene, bank approval required for partial amount --- `suspected_fraud`: Decline, suspected fraud --- `acquirer_routing_error`: Acquirer routing error --- `payment_rejected_other_reason`: Payment rejected (other reason) --- `authorization_failed`: Payment authorization failed --- `acquirer_error_cs`: Internal acquirer error. Please, contact support. --- `decline_irregular_transaction_pattern`: Declined by acquirer - irregular transaction pattern, please contact support --- `invalid_card_data`: Invalid card data provided --- `exceeded_terminal_limit`: Exceeded terminal limit --- `recurring_token_expired`: recurring token expired --- `soft_decline_contact_support`: Soft Decline - Please contact support for manual settlement of this purchase --- `payment_method_details_missing`: Missing payment_method_details message: type: string description: Verbose name and explanation of this error. status: $ref: '#/components/schemas/PurchaseStatus' status_history: type: array description: >- History of status changes, latest last. Might contain entry about a related object, e.g. status change to `refunded` will contain a reference to the refund Payment. items: properties: status: $ref: '#/components/schemas/PurchaseStatus' timestamp: $ref: '#/components/schemas/UnixTimestamp' related_object: nullable: true properties: type: type: string id: type: string format: uuid viewed_on: description: Time the payment form or invoice page was first viewed on nullable: true allOf: - $ref: '#/components/schemas/UnixTimestamp' company_id: type: string format: uuid is_test: type: boolean description: >- Indicates this is a test object, created using test API keys or using the merchant portal while in test mode. user_id: type: string format: uuid nullable: true description: >- ID of user who has created this object in the merchant portal, if applicable. brand_id: type: string format: uuid description: >- ID of the brand to create this Purchase for. Once registered, You can obtain at: https://portal.chip-in.asia/collect/developers/brands billing_template_id: type: string format: uuid nullable: true description: ID of a template that has spawned this Purchase, if any. client_id: type: string format: uuid nullable: true default: null description: >- ID of a Client object used to initialize ClientDetails (`.client`) of this Purchase. Either this field or specifying `.client` object is required (you can only specify a value for one of these fields). All `ClientDetails` fields from the Client will be copied to `.client` object. Note that editing Client object won't change the respective fields in already created Purchases. If you specify this field and your client saves a `recurring_token` (for instance, by saving their card), the respective ClientRecurringToken will be created. See the `/clients/{id}/recurring_tokens/` endpoint. send_receipt: type: boolean default: false description: Whether to send receipt email for this Purchase when it's paid. is_recurring_token: type: boolean description: >- Indicates whether a recurring token (e.g. for card payments - card token) was saved for this Purchase. If this is `true`, the `id` of this Purchase can be used as a `recurring_token` in `POST /purchases/{id}/charge/`, enabling you to pay for that Purchase using the same method (same card for card payments) that this one was paid with. recurring_token: type: string format: uuid nullable: true description: >- ID of a recurring token (Purchase having `is_recurring_token == true`) that was used to pay this Purchase, if any. skip_capture: type: boolean default: false description: >- Card payment-specific: if set to true, only authorize the payment (place funds on hold) when payer enters his card data and pays. This option requires a `POST /capture/` or `POST /release/` later on. You can use the preauthorization feature if you set this parameter to true and make the Purchase with `purchase.total == 0` (this can be achieved by providing a list of `purchase.products` with a total `price` of 0, or simply overriding the total using `purchase.total_override` to 0). The resulting Purchase can only be "paid" by the client (only cardholder data verification will happen, without a financial transaction) by card and will enforce saving the client's card. When this happens, the Purchase will have `status` of `preauthorized` and the `purchase.preauthorized` webhook callbacks will be emitted. Trying to use skip_capture (or preauthorization) without any payment methods that support the respective actions (this can be a result of `payment_method_whitelist` field being used) will result in an error on Purchase creation request step. Please check the `GET /payment_methods/` response for your desired Purchase parameters and/or consult with your account manager. force_recurring: type: boolean default: false description: >- If the used payment method supports recurring payment functionality, forces the customer's payment credentials to be saved for possible later recurring payments, without giving the customer a choice in the matter. reference_generated: type: string description: >- If you don't provide an invoice `reference` yourself, this autogenerated value will be used as a reference instead. reference: type: string maxLength: 128 description: Invoice reference. notes: type: string description: Add any additional informations. issued: description: >- Value for 'Invoice issued' field. Display-only, does not get validated. If not provided, will be generated as the current date in `purchase.timezone` at the moment of Purchase's creation. nullable: true allOf: - $ref: '#/components/schemas/Timestamp' due: description: >- When the payment is due for this Purchase. The default behaviour is to still allow payment once this moment passes. To change that, set `purchase.due_strict` to true. nullable: true allOf: - $ref: '#/components/schemas/UnixTimestamp' refund_availability: description: >- Specifies, if the purchase can be refunded fully and partially, only fully, partially or not at all. type: string enum: - all - full_only - partial_only - pis_all - pis_partial - none refundable_amount: x-summary: Amount available for refunds. allOf: - $ref: '#/components/schemas/MoneyAmount' currency_conversion: type: object nullable: true description: >- This object is present when automatic currency conversion has occurred upon creation of the purchase. Purchase's original currency was changed and its original amount was converted using the exchange rate shown here. properties: original_currency: type: string description: Currency this purchase was initially created with original_amount: type: integer description: Amount this purchase was initially created with exchange_rate: type: number description: >- Exchanged rate that was used for currency conversion. Original amount was multiplied by this number to calculate the new purchase amount. payment_method_whitelist: type: array minItems: 1 description: >- An optional whitelist of payment methods availble for this purchase. Use this field if you want to restrict your payer to pay using only one or several specific methods. Using this field and at the same time trying to use specific capabilities of a Purchase (e.g. `skip_capture` or charging it using a saved card token using `POST /purchases/{id}/charge/`) can cause a situation when there are no payment methods available for paying this Purchase. This will cause a validation error on Purchase creation. Please check the `GET /payment_methods/` response for your desired Purchase parameters and/or consult with your account manager. items: type: string description: Payment method name as returned by `GET /payment_methods/`. success_redirect: description: >- When Purchase is paid for successfully, your customer will be taken to this link. Otherwise a standard screen will be displayed. allOf: - $ref: '#/components/schemas/URL' failure_redirect: description: >- If there's a payment failure for this Purchase, your customer will be taken to this link. Otherwise a standard screen will be displayed. allOf: - $ref: '#/components/schemas/URL' cancel_redirect: description: >- If you provide this link, customer will have an option to go to it instead of making payment (a button with 'Return to seller' text will be displayed). Can't contain any of the following symbols: `<>'"` . Be aware that this does not cancel the payment (e.g. does not do the equivalent of doing the `POST /purchases/{id}/cancel/` request); the client will still be able to press 'Back' in the browser and perform the payment. allOf: - $ref: '#/components/schemas/URL' success_callback: description: >- When Purchase is paid for successfully, the `success_callback` URL will receive a POST request with the Purchase object's data in body. allOf: - $ref: '#/components/schemas/URL' creator_agent: type: string maxLength: 32 description: >- Identification of software (e.g. an ecommerce module and version) used to create this purchase, if any. platform: type: string enum: - web - api - ios - android - macos - windows description: Platform this Purchase was created on. product: type: string enum: - purchases description: Defines which gateway product was used to create this Purchase. created_from_ip: type: string format: IP description: IP the Purchase was created from. invoice_url: description: >- URL you will be able to access invoice for this Purchase at, if applicable nullable: true allOf: - $ref: '#/components/schemas/URL' checkout_url: description: >- URL you will be able to access the checkout for this Purchase at, if payment for it is possible. When building integrations, redirect the customer to this URL once purchase is created. You can add the `preferred` query arg to the `checkout_url` in order to force redirect the client straight to the checkout for a specific payment method (`?preferred={payment_method}`, where `{payment_method}` is the payment method name as returned by `GET /payment_methods/`). If this method redirects the client further to a different system and no customer data entry is needed on gateway's checkout page, your payer will be taken straight to that page (not seeing the gateway's checkout UI); otherwise, he will see the payment method entry UI on the gateway checkout page. allOf: - $ref: '#/components/schemas/URL' direct_post_url: description: >- URL that can be used for Direct Post integration. This functionality is activated for each merchant account individually. Please consult with your account manager if you wish to use it. Will be null if payment for purchase is not possible, `purchase.request_client_details` isn't empty or success_redirect/failure_redirect are not provided - these all break the usual direct post flow. To leverage Direct Post checkout, create a `` having `method="POST" action=""` and include the following inputs: `cardholder_name: text, Latin letters only (space and apostrophe (`'`), dot (`.`), dash (`-`) symbols are also allowed), max 30 chars` --- `card_number: text, digits only, no whitespace, max 19 chars` --- `expires: text in 'MM/YY' format, digits and a slash only /^\d{2}\/\d{2}$/, max 5 chars` --- `cvc: numeric string of 3 or 4 digits` --- `remember_card: checkbox with value="on" (the default when omitting value attribute of a checkbox input)` Ensure the validation as listed above! Validation errors will be treated as payment failures. Obviously, you can style this form to fit in with the rest of your website. When your payer submits this form (don't forget a `