Iframe API Step 2
When a user makes a payment using the form displayed inside the Iframe (STEP 1), the CoinPays system makes a request to the merchant’s Callback URL. CoinPays system must receive a response for this request. Otherwise, the payment process will not be considered as completed and the merchant will not be paid.
The result of each payment process (success or failed) will be sent separately to the Callback URL by CoinPays system. In response to this request, the merchant will have to approve or cancel the user’s order and respond by simply displaying OK to inform the CoinPays system.
POST REQUEST FIELDS AND VALUES sent to the Callback URL by the CoinPays system:
| Field name | Success | Failed |
|---|---|---|
hash | Yes | The hash value generated to check the received values are intact for security purposes (See the sample codes for the calculation) |
merchant_id | Yes | Merchant ID |
merchant_oid | Yes | Merchant order id: The unique order ID set for the transaction and sent in STEP 1. |
status | Yes | The result of the payment (‘success’ or ‘failed’) |
total_amount | Yes | Total amount collected from the user (Multiplied by 100: e.g. 34.56 => 3456) |
currency | Yes | Indicates the currency of payment. 'TL', 'USD', 'EUR', 'GBP', 'RUB', etc... |
crypto_amount | Yes | Total calculated crypto payment amount. Example value: 0.0002456 |
crypto_token | Yes | Indicates the crypto currency of payment. 'ETH', 'BTC', 'BNB', 'AREA', 'XRP', etc... |
crypto_token_network | Yes | Indicates the crypto network of crypto token. 'AREON', 'ERC-20', 'BEP-20',, etc... |
test_mode | Yes | Sent as 1 in test mode or while running a test in live mode |
failed_reason_msg | No | Explains why the payment is not approved (Only in English for now) |
The RESPONSE that the Callback URL gives to the CoinPays system should be plain text OK
IMPORTANT WARNINGS:
You should not restrict access to your Callback URL by any means such as session control, etc. This is vital for the CoinPays system to reach the page.
You should not display HTML or any other content before or after the “OK” response.
Callback URL is not a page which users see during payment process, thus there will be no user SESSION at this page and no SESSION values can be used. CoinPays system submits a POST which contains relevant information such as “merchant_oid”.
For payments which the CoinPays system does not receive an OK response from the Callback URL, the status will be displayed as "In Progress" on the Transactions page on the Merchant Panel.
When the CoinPays system can not connect to the Callback URL or does not receive the OK response from the Callback URL, CoinPays system will try again after a minute. This may happen due to network issues, instant overloads on merchant systems, etc. Thus, multiple notifications for the same payment transaction can be received on Callback URL. For this reason, in such cases, it is very important that recurring notifications should be handled correctly on Callback URL. Only the first notification should be taken into account to approve/cancel the order and the recurring ones should only be responded to by displaying OK. Recurring notifications should be checked based on “merhant_oid” value.
It is crucial for security reasons to check that the hash value in POST is the same as the hash value that will be created using the related values in POST. This is necessary to ensure that the POST request comes from the CoinPays system and the values do not change during transport. Be warned that if you do not check hash value, you may face financial losses.
To verify that the Callback URL is created in accordance with the explanations given above, a test payment should be made.
If the status of test payment is displayed as "Successful" on the Transactions page on CoinPays Merchant Panel, the CoinPays integration is complete.
If the status of test payment is displayed as "In Progress", it means that the CoinPays system has not received "OK" response from the Callback URL. Click on the "Detail" link of the test payment on the Transactions page and check what response CoinPays system receives from the Callback URL to debug.
Last updated