Iframe API Step 2
Last updated
Last updated
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.
Field name | Success | Failed |
---|---|---|
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.
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)