Payment Callback

After a payment request is made and the user navigates to the Paymento gateway to complete the payment, the user is redirected back to the merchant's Return URL (Given in Payment Request) with a specific status. This allows the merchant to update the order status in their interface. However, it is crucial for merchants to use the Set Payment Settings API to define the IPN URL for receiving payment statuses and to verify the payment using the Verify Payment API.

Redirect and Callback Data

Paymento returns the following variables in the Callback (to Return URL and IPN URL):

HTTP Headers

Name	Value
X-HMAC-SHA256-SIGNATURE	“Signature hash…”

Body Patameters

Name	Description
Token	Token of the payment order.
PaymentId	The order ID in Paymento (Payment ID, as a long number).
OrderId	The order ID from the online store (as a string).
OrderStatus	The order status (explained in next paragraph)
AdditionalData	The payment request's additional data.

Order Statuses

When the user completes or cancels the payment, Paymento redirects them to the specified callback URL with one of the following statuses:

• Initialize (0): Payment request accepted by the API.

• Pending (1): User has chosen a coin to pay.

• PartialPaid (2): User paid less than the order amount.

• WaitingToConfirm (3): User's transaction received in the blockchain network (in mempool or block).

• Timeout (4): Payment deadline expired.

• UserCanceled (5): User clicked on the cancel button at the gateway.

• Paid (7): User's transaction confirmed in the blockchain network.

• Approve (8): Payment verified by the store.

• Reject (9): Address assigned for the user's payment is no longer monitored, or payment not verified by the store.

HMAC Signature Verification

To ensure the integrity and authenticity of callbacks from Paymento, we use HMAC-SHA256 signatures. For each callback, Paymento includes a signature in the X-Hmac-Sha256-Signature header. To verify this signature:

1. Obtain the raw payload of the callback (the entire body of the POST request).

2. Use your secret key (Provided in your Paymento dashboard).

3. Calculate the HMAC-SHA256 hash of the payload using your secret key.

4. Convert the resulting hash to uppercase hexadecimal format.

5. Compare this calculated signature with the one received in the X-Hmac-Sha256-Signature header.

// The signatures should match exactly. Here's a pseudo-code example:

receivedSignature = headers['X-HMAC-SHA256-SIGNATURE']
payload = request.rawBody
secretKey = "Your-Secret-Key-From-Paymento-Dashboard"
calculatedSignature = uppercase(hmac_sha256(payload, secretKey))
isValid = (calculatedSignature == receivedSignature)

Important notes

Do Not Rely Solely on Redirect to Return URL: Merchants must use the IPN URL set in the "Set Payment Settings API" to receive real-time payment status updates.

Always Verify Payments: Even after receiving a "Paid" status, always verify the payment using the Verify Payment API to ensure the transaction is confirmed on the blockchain and status update came from Paymento.

Call Back Example

curl 
-X POST https://yoursite.com/shop/payment-result 
-H 'Accept: application/json' 
-H 'HMAC_SHA256_SIGNATURE: vBvDwCix13cq7anuf5eleiOXjFApBLxEWC2G2lgnJTU=' 
-H 'Content-Type: application/json' 
-d '{"Token":"d1179e54e58d4e51a285a5c659a2b7ef","PaymentId":20016,"OrderId":"etp-3900","OrderStatus":3,"AdditionalData":[]}'