Recurring Charges

In summary once a customer has successfully made their initial payment using a card, you have the option to store their card authorization and utilize it for future transactions. It's important to note that this functionality is currently only applicable for card payments.

Charge the first transaction

You can initiate the first charge either from a web application or a mobile app. Explore the various integration methods available for both web and mobile platforms to effectively implement this functionality.

Why is charging the user required when adding their cards?

1. Local regulations mandate that users must undergo a two-factor authentication (2FA) process during the initial transaction to authenticate their card. Only after successful authentication can we proceed with charging the card for subsequent transactions.

2. This requirement enables us to verify the validity of the card and ensures that it can be used for subsequent transactions without any issues.

Minimum charge amount

We suggest a minimum amount of ILS 0.5, JOD 0.1, or USD 0.20 for the initial charge. Please note that lower amounts may not be guaranteed to work with all card brands or banks.

As part of our standard practice, we credit the user's app with a value equivalent to the tokenization amount, or alternatively, we issue a refund for the charged amount. This ensures that the user's funds are not permanently deducted and provides a seamless experience for them.

Get the Card authorization

Upon a successful first transaction, you have two options for obtaining transaction updates. Firstly, you can set up a webhook endpoint to receive events in real-time. Alternatively, you can utilize the Verify Transaction API endpoint to check the status of the transaction. In both cases, the response will follow the sample format provided below:

{  
  ...
  "data": {  
    ...
    "authorization": {  
      "authorization_code":"AUTH_XXXXXX",
      "card_type":"visa",
      "last4":"0444",
      "exp_month":"01",
      "exp_year":"2023",
      "bin":"401234",
      "bank":"TEST BANK",
      "channel":"card",
      "signature": "SIG_XXXXXX",
      "reusable":true,
      "country_code":"PS",
    },
    ...
  }  
}

In the response, you will observe that the data object includes an authorization object. This authorization object provides detailed information about the payment instrument used by the user, specifically the card details.

Store the authorization

Afterwards, you should save the authorization information and the email used for the transaction. These details will be useful for charging the card in future transactions. It's important to note that each payment method used on your website or app has a unique identifier. This identifier helps prevent the storage of duplicate authorizations, so you won't save the same information multiple times.

To maintain complete card-related information, it is crucial to store the entire authorization object. This ensures that no context is lost regarding the card details.

Additionally, it is essential to store the email address used during the authorization creation process. Only the email associated with the initial authorization can be used for subsequent charges. If you rely on the user's email stored in your system and the user modifies it, the authorization will no longer be chargeable. Therefore, storing the original email used for authorization is necessary to ensure the successful processing of future charges.

By saving the complete authorization object, you gain the ability to display the customer's payment details during subsequent payment attempts. This allows for a seamless recurrent charging process. For instance, when the user intends to make another payment, you can conveniently present the card details as "Bank of Palestine Visa card ending with 1234" to the user. This facilitates a smooth and straightforward payment experience.

Charge the authorization

When the user chooses a specific card for a new transaction or when you need to charge them in subsequent transactions, you will need to send the authorization code, the user's email, and the desired amount to the Charge Authorization API. This API enables you to initiate the charge process by providing the necessary information to authorize the transaction and complete the payment.

Request

curl https://api.lahza.io/transaction/charge_authorization
-H "Authorization: Bearer YOUR_SECRET_KEY"
-H "Content-Type: application/json"
-d '{ "authorization_code" : "AUTH_XXXXXXX", email: "[e-mail]", amount: "10000" }'
-X POST

Response

{
  "status": true,
  "message": "Charge attempted",
  "data": {
    "amount": 10000,
    "currency": "ILS",
    "transaction_date": "2023-06-01T10:12:13.000Z",
    "status": "success",
    "reference": "asjdasd823jds",
    "domain": "test",
    "metadata": "",
    "gateway_response": "Approved",
    "message": null,
    "channel": "card",
    "ip_address": null,
    "log": null,
    "fees": 14500,
    "authorization": {
      "authorization_code": "AUTH_asokdjsakdja",
      "bin": "13467",
      "last4": "4011",
      "exp_month": "11",
      "exp_year": "2023",
      "channel": "card",
      "card_type": "visa DEBIT",
      "bank": "Test Bank",
      "country_code": "PS",
      "brand": "visa",
      "reusable": true,
      "signature": "SIG_oajdskaJjsd82",
    },
    "customer": {
      "id": 123,
      "first_name": null,
      "last_name": null,
      "email": "[e-mail]",
      "customer_code": "CUS_klmasdmka82",
      "phone": null,
      "metadata": null,
      "risk_action": "default"
    },
    "plan": null,
    "id": 12312456
  }
}

Interval-based Charging If your application requires charging authorizations at specific intervals, you will need to set up a cron job on your server. This cron job will run at designated intervals and retrieve all the authorizations that need to be charged.