Card Charge

Belema card charge enables a merchant to accept card payment from customers.

1. Checkout
2. Direct API Integration (Requires PCI-DSS certification)  

Checkout this link for the direct checkout process using our javascript library 

https://belemagatewaydeveloperdocumentation.tawk.help/article/overview

Belema card charge enables a merchant to accept card payment from customers. The card charge endpoint allows a customer to provide encrypted card information and also the secret API key in the header and sends it to the server to initiate a card payment.

• Merchant Account: Client needs to be registered on the Payment Gateway as a merchant and submit all required compliance documents.
  
  
• WebHook URL (optional): Client can also submit a webhook URL for transaction notification on the PG to receive payment notifications
  
  
• Retrieve Encryption Key: Asymmetric key encryption (RSA) is used to encrypt the card information. The key is provided to the client after successfully completing KYC and submitting PCI-DSS certificate.
  
  
• PCI/DSS: A merchant can only accept card payments from customers provided they have PCI/DSS certification. Supported cards schemes are:
• Mastercard
• Visa
• Verve
  

• Reference: The randomly generated transaction reference up to 15 characters

• Amount: The transaction amount in Naira
  
  

• Email: The email address of the customer
  
  

• Phone: The optional customer phone number

• Currency: Defaults to NGN  
  
  

• Meta: Enable Merchant to pass Custom that would also be returned in the merchant webhook response. Prefer to use JsonElement
  
  

• SplitPayment: Enables a merchant to split the original transaction amount into different sub-wallets during transaction initialization. With this option merchant can specify where the money goes into. 
  
  

Sample Request

You can use your secret test key for test transaction and card charge. The key can be retrieved from the merchant dashboard.

Response

Step 2: Retrieve the RSA encryption key by calling this endpoint: https://gateway.belemafintech.com/api/Checkout/merchant/encryption-key. The response comes with the public rsa key that you must use to encrypt the card data  

RSA Encryption in C# Example

RSA Encryption PHP Example

• The key should be in pem format. It should start with
  -----BEGIN PUBLIC KEY-----
  and ends with
  -----END PUBLIC KEY-----

• The encrypted result should be in base64 string
• The padding is in Pkcs1 format

Step 3: Invoke the card charge endpoint that takes the following request payload:

The request body takes the reference generated in step 1 and the encrypted card data in the following format:

pan:expiry:cvv:otp:pin

Example:
5399839226202454:04/50:111::1234

By default, the OTP is empty. It will be sent in the next request that performs otp authentication. The first request usually sends the otp, then the second perform otp authentication with the otp included in the card data format

Response

The response code "T0" or msgCode "MSG0086" means that otp authentication is required.

Step 4: Encrypt the card again this time around including the otp in the encrypted card format:

5399839226202454:04/50:111:908909:1234 

Send the request again to the same endpoint and the final response is successful.

The responseCode "00" simply means the card charge has been completed successfully. 

Note: In some cases, OTP may be disabled by the card bank, so step 2 becomes un-necessary.

Visa Card Charge Response

For visa cards, If the responseCode is “S0” it simply means that 3DS authentication is required. The response comes with a html and the responseCode is “S0”. One you get this response, return it to the user and then the user clicks on the button to finalize the payment on the 3DS

MSG0086:OTP Authentication is required for card charge

MSG200:All MSG200 are success codes, and it comes with an Http Status code of 200. Any code is not MSG200 is normally a bad request and usually comes with an Http status code of 400

MSG0013:Transaction reference already exists

MSG003:Merchant not found

MSG0096:Merchant wallet not found

MSG0017:Insufficient funds

MSG0080:Minimum transfer amount check

MSG0090:Maximum transfer amount check

MSG0094:Cannot withdraw because starter business limit reached

MSG004:No transfers found when fetching transfers