Charges

Overview

To charge a credit or debit card, submit a request to create a charge using the Create a Charge endpoint. You can also retrieve and refund individual charges, as well as list all charges. Charges are identified by a unique charge_id.

To charge a credit or debit card or capture an authorized transaction, use the Create a Chargeendpoint.

The Payment Source

In the charge request, include source.id to indicate the payment source at the time of the transaction. Here are the possible values that source.id can accept.

Source ID	Description
`src_sa.mada`	mada (local payment switch in KSA). For this payment method, a `transaction.url` is always returned. Hence the user has to be redirected to this page after the Charge is `INITIATED`.
`src_kw.knet`	KNET (local payment switch in Kuwait). For this payment method, a `transaction.url` is always returned. Hence the user has to be redirected to this page after the Charge is `INITIATED`.
`src_eg.fawry`	FAWRY (local payment switch in Egypt). For this payment method, a `transaction.url` is always returned with the Fawry order details. Hence the user has to be redirected to this page after the Charge is `IN PROGRESS` so that the user can complete the payment at the Fawry Store.
`src_bh.benefit`	Benefit (local payment switch in Bahrain). For this payment method, a `transaction.url` is always returned. Hence the user has to be redirected to this page after the Charge is `INITIATED`.
`token_id`	To capture the amount using the `token.id` generated from Create a Token or Card SDK or Checkout SDK.
`authorize_id`	To capture the amount using the `authorize.id` generated from Create an Authorize.
`src_card`	To display ONLY the Card payment methods on a Tap hosted page. The Create a Charge will return the `transaction.url` for redirecting the user to the Tap hosted page.
`src_all`	To display all the payment methods enabled for the Merchant ID on a Tap hosted Page. The Create a Charge will return the `transaction.url` to redirect the user to the Tap hosted page.

📘
Redirect Payment Flow
For KNET, mada, Benefit and 3D Secure transactions, redirect.url should be passed in the Charges Request.

The Charges Request Example

{
  "amount": 10,
  "currency": "KWD",
  "threeDSecure": true,
  "save_card": false,
  "description": "Test Description",
  "statement_descriptor": "Sample",
  "metadata": {
    "udf1": "test 1",
    "udf2": "test 2"
  },
  "reference": {
    "transaction": "txn_0001",
    "order": "ord_0001"
  },
  "receipt": {
    "email": false,
    "sms": true
  },
  "customer": {
    "first_name": "test",
    "middle_name": "test",
    "last_name": "test",
    "email": "[email protected]",
    "phone": {
      "country_code": "965",
      "number": "50000000"
    }
  },
  "merchant": {
    "id": ""
  },
  "source": {
    "id": "src_kw.knet"
  },
  "destinations": {
    "destination": [
      {
        "id": "480593",
        "amount": 2,
        "currency": "KWD"
      },
      {
        "id": "486374",
        "amount": 3,
        "currency": "KWD"
      }
    ]
  },
  "post": {
    "url": "http://your_website.com/post_url"
  },
  "redirect": {
    "url": "http://your_website.com/redirect_url"
  }
}

The Charges Request Example in the marketplace

To split the amount, add a Destinations Object to the charge request. Obtain the Destination ID when creating a business for your sub-merchants. This feature allows for automatic splitting of the amount between your sub-merchants.

"destinations": {
    "destination": [
      {
        "id": "480593",
        "amount": 2,
        "currency": "KWD"
      },
      {
        "id": "486374",
        "amount": 3,
        "currency": "KWD"
      }
    ]
  },

The Charges Response

If the charge request is valid, then Tap will return the charge response which includes the "status" field defining the status of the charge. The possible values are below

INITIATED, ABANDONED, CANCELLED, FAILED, DECLINED, RESTRICTED, CAPTURED, VOID, TIMEDOUT, UNKNOWN

INITIATED - Tap will provide the payment URL (transaction.url) to process the payment. The customer should be redirected to this URL in order to complete the payment.

CAPTURED - Amount was successfully charged.

ABANDONED, CANCELLED, FAILED, DECLINED, RESTRICTED, VOID, TIMEDOUT, UNKNOWN - Payment failed. Use the charge response code and message to identify the reason for failure.

customer.id
If you did not provide a customer ID in the charge request, Tap will create a customer ID for each successful transaction and share it within the charge response. You can store this customer ID for future charges, authorizations, or for getting the list of charges or authorized transactions. You can also create a customer using Create a Customer

card.id
If you requested to save the card in the charge request, Tap will save the card and provide a card ID in the charge response if the transaction is successful. You can save this card ID and use it for future charges or authorizations. However, the card ID cannot be used directly in the charge or authorization request. You must first create a token ID using the saved card's ID and then pass the token ID along with the customer ID in the charge or authorization request.

**Payment Response Code
The payment response code and message will also be provided in the charge response. Refer to Errors for error responses.

The Charges Response Example

{
  "id": "chg_LV015020211650Hl3j1006577",
  "object": "charge",
  "live_mode": true,
  "api_version": "V2",
  "method": "GET",
  "status": "CAPTURED",
  "amount": 52.65,
  "currency": "KWD",
  "threeDSecure": true,
  "card_threeDSecure": false,
  "save_card": false,
  "merchant_id": "",
  "product": "",
  "description": "",
  "metadata": {
    "customerId": "cus_LV064920211650Kc561006769"
  },
  "transaction": {
    "authorization_id": "634783",
    "timezone": "UTC+03:00",
    "created": "1623343863977",
    "expiry": {
      "period": 30,
      "type": "MINUTE"
    },
    "asynchronous": false,
    "amount": 52.65,
    "currency": "KWD"
  },
  "reference": {
    "track": "tck_LV025020211650n3Z51006593",
    "payment": "5010211650065932654",
    "gateway": "202116116582392",
    "acquirer": "116136012364"
  },
  "response": {
    "code": "000",
    "message": "Captured"
  },
  "receipt": {
    "id": "205110211650060732",
    "email": true,
    "sms": true
  },
  "customer": {
    "id": "cus_LV064920211650Kc561006769"
  },
  "source": {
    "object": "source",
    "type": "CARD_NOT_PRESENT",
    "payment_type": "DEBIT",
    "payment_method": "KNET",
    "channel": "INTERNET",
    "id": "src_kw.knet"
  },
  "redirect": {
    "status": "SUCCESS",
    "url": "https://www.cchyper.com/retailers/1434/_external-payment-completed?externalPaymentKey=1c1ab3c351737a99dfa7e1799055a8c44bd232ce89e6111b8978e2148067"
  },
  "refunds": {
    "refund": [
      {
        "id": "re_LV034920210800n5T51106744",
        "amount": 4.48,
        "currency": "KWD",
        "created": "1623398449853",
        "status": "PENDING"
      }
    ]
  }
}