> ## 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. # Create a webhook > Create a webhook using the values provided in the parameters. The webhook enables the recipient to receive notifications via callback url when selected events occur. ## OpenAPI ````yaml _openapi-chip-collect POST /webhooks/ 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: /webhooks/: post: tags: - Webhooks summary: Create a webhook description: > Create a webhook using the values provided in the parameters. The webhook enables the recipient to receive notifications via callback url when selected events occur. operationId: webhooks_create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookBody' responses: '201': $ref: '#/components/responses/Webhook' '400': $ref: '#/components/responses/400' security: - bearerAuth: [] components: schemas: WebhookBody: allOf: - $ref: '#/components/schemas/BaseModelBody' - description: >- Defines a webhook rule to an external server. The `callback` URL will receive a POST request with the related object's (e.g. Purchase for `purchase.*` webhooks) data in body when any of the events (see the description of `events` field below) it is configured to listen for are triggered. The payload object will additionally include an "event_type" field to indicate which event type (see the Webhook.events field) triggered the webhook. Note that, as well as with the rest of dataset, test and live Webhooks are separate; test webhooks will not handle events caused by live Purchases, and vice-versa. required: - title - events - callback properties: title: type: string maxLength: 100 description: Arbitrary title of webhook all_events: type: boolean default: false description: >- Specifies this webhook should trigger on all event types. Either this or `events` is required. public_key: $ref: '#/components/schemas/PublicKeyBody' events: type: array minItems: 1 uniqueItems: true description: >- List of events to trigger webhook callbacks for. Either this or `all_events` is required. items: $ref: '#/components/schemas/EventBody' callback: $ref: '#/components/schemas/URLBody' BaseModelBody: type: object PublicKeyBody: type: string description: >- PEM-encoded RSA public key for authenticating webhook or callback payloads EventBody: type: string description: >- Available event types and when they are emitted: `purchase.created`: Emitted when a Purchase is created. This happens as a result of POST /purchases/ request executed successfully. Purchase.status will be == `created` in the received payload. --- `purchase.paid`: Emitted when a Purchase is paid for. Purchase.status will be == `paid`. Happens when a payform is submitted (for a Purchase having `skip_capture == false`) and a successful payment is done by the payer or in case of /capture/ or /charge/ API requests executed successfully. --- `purchase.payment_failure`: Emitted when payer submits a payment using the payform, but it doesn't complete successfully (e.g. because payer's account balance is insufficient). Purchase.status will be == `error`. --- `purchase.refund_failure`: Emitted when a pending refund fails. --- `purchase.capture_failure`: Emitted when a pending capture fails. The Purchase status is expected to be 'hold' after that. --- `purchase.release_failure`: Emitted when a pending release fails. The Purchase status is expected to be 'hold' after that. --- `purchase.pending_execute`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_execute` Purchase status. When transaction becomes finalized, a `purchase.paid`, `purchase.hold` or `purchase.payment_failed` callback will be emitted. --- `purchase.pending_charge`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_charge` Purchase status. When transaction becomes finalized, a `purchase.paid` or `purchase.payment_failed` callback will be emitted. --- `purchase.cancelled`: Emitted once POST /purchases/{id}/cancel/ request succeeds. It won't be possible to pay for the related Purchase after that. Purchase.status will be == `cancelled`. --- `purchase.hold`: Emitted when a Purchase having `skip_capture == true` has its payform submitted and "payment" performed successfully. The specified amount of funds will be placed on hold. Purchase.status will be == `hold`. --- `purchase.captured`: Emitted when the POST /purchases/{id}/capture/ request for a Purchase that previously had the status of `hold` succeeds. Purchase.status will be == `paid`. --- `purchase.pending_capture`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_capture` Purchase status. When transaction becomes finalized, a `purchase.captured` callback will be emitted. --- `purchase.released`: Emitted when the POST /purchases/{id}/release/ request for a Purchase that previously had the status of `hold` succeeds. Funds reserved will be released with no payment performed. Purchase.status will be == `released`. --- `purchase.pending_release`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_release` Purchase status. When transaction becomes finalized, a `purchase.released` callback will be emitted. --- `purchase.preauthorized`: Emitted when preauthorization scenario (see description for the Purchase.skip_capture field) is executed successfully. Purchase will have a status of `preauthorized`. --- `purchase.recurring_token_deleted`: Emitted when the POST /purchases/{id}/delete_recurring_token/ request is executed successfully, deleting the recurring token associated with a Purchase. Purchase status will be the same as it were prior to this event. --- `purchase.pending_recurring_token_delete`: Emitted when token deletion takes longer than expected on the acquirer side. When operation is finalized, a `purchase.recurring_token_deleted` callback will be emitted. --- `purchase.pending_refund`: Emitted when refund transaction execution takes longer than expected on the acquirer side. See `pending_refund` Purchase status. When refund becomes finalized, a `payment.refunded` callback will ne emitted. --- `payment.refunded`: Emitted when a Purchase is refunded (as a result of POST /purchases/{id}/capture/ request done successfully or action performed in company's frontoffice system). The returned data will be a Payment object generated as a result of this action. A link to the original Purchase (that will have a status of `refunded`) will be present in the `related_to` field of this Payment. --- `payout.pending`: Emitted when Payout execution has been initiated and is currently processing. --- `payout.failed`: Emitted when a Payout processing was completed with an error. Payout.status will be == `error`. Note that payouts can spend up to 3-5 days (depending on the payout provider) in processing after being initiated. --- `payout.success`: Emitted when a Payout is successfully processed. Payout.status will be == `success`. Note that payouts can spend up to 3-5 days (depending on the payout provider) in processing after being initiated. --- `payment.charged_back`: Emitted when a Payment is charged_back. --- `purchase.viewed`: Emitted when a Purchase is viewed. --- `purchase.settled`: Emitted when a Purchase is settled. --- `payout.created`: Emitted when a Payout is created. --- `payment.chargeback_reversed`: Emitted when a Payment chargeback is reversed. enum: - purchase.created - purchase.paid - purchase.payment_failure - purchase.refund_failure - purchase.capture_failure - purchase.release_failure - purchase.pending_execute - purchase.pending_charge - purchase.cancelled - purchase.hold - purchase.captured - purchase.pending_capture - purchase.released - purchase.pending_release - purchase.preauthorized - purchase.pending_recurring_token_delete - purchase.recurring_token_deleted - purchase.pending_refund - payment.refunded - payout.pending - payout.failed - payout.success - payment.charged_back - purchase.viewed - purchase.settled - payout.created - payment.chargeback_reversed URLBody: type: string format: url maxLength: 500 Webhook: allOf: - $ref: '#/components/schemas/BaseModel' - description: >- Defines a webhook rule to an external server. The `callback` URL will receive a POST request with the related object's (e.g. Purchase for `purchase.*` webhooks) data in body when any of the events (see the description of `events` field below) it is configured to listen for are triggered. The payload object will additionally include an "event_type" field to indicate which event type (see the Webhook.events field) triggered the webhook. Note that, as well as with the rest of dataset, test and live Webhooks are separate; test webhooks will not handle events caused by live Purchases, and vice-versa. required: - title - events - callback properties: title: type: string maxLength: 100 description: Arbitrary title of webhook all_events: type: boolean default: false description: >- Specifies this webhook should trigger on all event types. Either this or `events` is required. public_key: $ref: '#/components/schemas/PublicKey' events: type: array minItems: 1 uniqueItems: true description: >- List of events to trigger webhook callbacks for. Either this or `all_events` is required. items: $ref: '#/components/schemas/Event' callback: $ref: '#/components/schemas/URL' BaseModel: type: object properties: type: type: string description: Object type identifier id: type: string format: uuid created_on: description: Object creation time allOf: - $ref: '#/components/schemas/UnixTimestamp' updated_on: description: Object last modification time allOf: - $ref: '#/components/schemas/UnixTimestamp' PublicKey: type: string description: >- PEM-encoded RSA public key for authenticating webhook or callback payloads example: |- -----BEGIN PUBLIC KEY----- MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA6gLlBKxCB5dxPJbinCzl hOfKSgQtOWQQBxmnWIkEVUbqhpnqr3xNYiAvDyMUxYUwuzN44eHO+mR9MZWcSx3c bXmKa3gsOzR6GdcOxMGaVxvfje+fujCAlCtO1BP+A9/FS3KcPgCYG1wtAPwA5IAf HylL3TsUVIJQFBgiBr6N4Bgapr9eloaFfeYIBRsXmxPKAMJivqxYpLh0V3N4ZFd5 TGqSEAa4b1ULDr6p0sB2L3QikTdsF0zp03zNceKA6fXDOzD0xWtg9buXvyKwePK4 M2kcnWBNfsWghrdg0fG3O9bmkaS1oEXydrmJfuiI8h6a64J/1nzooi2yLC9D6Ta0 S63bbuAHymnQtiNuV7Ixp6IoTGFaS88aTiHaP8rdyWV8JTDFx0qeDzyaGWiYGwEF mj/buHCEcRhoajbGkPhYA4YEdn4jy1wZhEr2OMdBPM7mPPI0Hy3hcNJVMVVlrpHe IltQATpjlNaJMlRPjbcaiW7dsO3BuF9ZOMGksSOnyYm/AgMBAAE= -----END PUBLIC KEY----- Event: type: string description: >- Available event types and when they are emitted: `purchase.created`: Emitted when a Purchase is created. This happens as a result of POST /purchases/ request executed successfully. Purchase.status will be == `created` in the received payload. --- `purchase.paid`: Emitted when a Purchase is paid for. Purchase.status will be == `paid`. Happens when a payform is submitted (for a Purchase having `skip_capture == false`) and a successful payment is done by the payer or in case of /capture/ or /charge/ API requests executed successfully. --- `purchase.payment_failure`: Emitted when payer submits a payment using the payform, but it doesn't complete successfully (e.g. because payer's account balance is insufficient). Purchase.status will be == `error`. --- `purchase.refund_failure`: Emitted when a pending refund fails. --- `purchase.capture_failure`: Emitted when a pending capture fails. The Purchase status is expected to be 'hold' after that. --- `purchase.release_failure`: Emitted when a pending release fails. The Purchase status is expected to be 'hold' after that. --- `purchase.pending_execute`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_execute` Purchase status. When transaction becomes finalized, a `purchase.paid`, `purchase.hold` or `purchase.payment_failed` callback will be emitted. --- `purchase.pending_charge`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_charge` Purchase status. When transaction becomes finalized, a `purchase.paid` or `purchase.payment_failed` callback will be emitted. --- `purchase.cancelled`: Emitted once POST /purchases/{id}/cancel/ request succeeds. It won't be possible to pay for the related Purchase after that. Purchase.status will be == `cancelled`. --- `purchase.hold`: Emitted when a Purchase having `skip_capture == true` has its payform submitted and "payment" performed successfully. The specified amount of funds will be placed on hold. Purchase.status will be == `hold`. --- `purchase.captured`: Emitted when the POST /purchases/{id}/capture/ request for a Purchase that previously had the status of `hold` succeeds. Purchase.status will be == `paid`. --- `purchase.pending_capture`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_capture` Purchase status. When transaction becomes finalized, a `purchase.captured` callback will be emitted. --- `purchase.released`: Emitted when the POST /purchases/{id}/release/ request for a Purchase that previously had the status of `hold` succeeds. Funds reserved will be released with no payment performed. Purchase.status will be == `released`. --- `purchase.pending_release`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_release` Purchase status. When transaction becomes finalized, a `purchase.released` callback will be emitted. --- `purchase.preauthorized`: Emitted when preauthorization scenario (see description for the Purchase.skip_capture field) is executed successfully. Purchase will have a status of `preauthorized`. --- `purchase.recurring_token_deleted`: Emitted when the POST /purchases/{id}/delete_recurring_token/ request is executed successfully, deleting the recurring token associated with a Purchase. Purchase status will be the same as it were prior to this event. --- `purchase.pending_recurring_token_delete`: Emitted when token deletion takes longer than expected on the acquirer side. When operation is finalized, a `purchase.recurring_token_deleted` callback will be emitted. --- `purchase.pending_refund`: Emitted when refund transaction execution takes longer than expected on the acquirer side. See `pending_refund` Purchase status. When refund becomes finalized, a `payment.refunded` callback will ne emitted. --- `payment.refunded`: Emitted when a Purchase is refunded (as a result of POST /purchases/{id}/capture/ request done successfully or action performed in company's frontoffice system). The returned data will be a Payment object generated as a result of this action. A link to the original Purchase (that will have a status of `refunded`) will be present in the `related_to` field of this Payment. --- `payout.pending`: Emitted when Payout execution has been initiated and is currently processing. --- `payout.failed`: Emitted when a Payout processing was completed with an error. Payout.status will be == `error`. Note that payouts can spend up to 3-5 days (depending on the payout provider) in processing after being initiated. --- `payout.success`: Emitted when a Payout is successfully processed. Payout.status will be == `success`. Note that payouts can spend up to 3-5 days (depending on the payout provider) in processing after being initiated. --- `payment.charged_back`: Emitted when a Payment is charged_back. --- `purchase.viewed`: Emitted when a Purchase is viewed. --- `purchase.settled`: Emitted when a Purchase is settled. --- `payout.created`: Emitted when a Payout is created. --- `payment.chargeback_reversed`: Emitted when a Payment chargeback is reversed. enum: - purchase.created - purchase.paid - purchase.payment_failure - purchase.refund_failure - purchase.capture_failure - purchase.release_failure - purchase.pending_execute - purchase.pending_charge - purchase.cancelled - purchase.hold - purchase.captured - purchase.pending_capture - purchase.released - purchase.pending_release - purchase.preauthorized - purchase.pending_recurring_token_delete - purchase.recurring_token_deleted - purchase.pending_refund - payment.refunded - payout.pending - payout.failed - payout.success - payment.charged_back - purchase.viewed - purchase.settled - payout.created - payment.chargeback_reversed URL: type: string format: url maxLength: 500 UnixTimestamp: type: integer format: Unix timestamp (seconds) example: 1619740800 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" } } Webhook: description: OK content: application/json: schema: $ref: '#/components/schemas/Webhook' securitySchemes: bearerAuth: type: http scheme: bearer ````