Callbacks
When YaPay receives payment result, system will send callback to URLs, provided by merchant.
Callback settings
Merchant can provide any amount of callback URLs with following settings:
providerId- identifier that describes payment results of which payment system should be triggered on this URL. List of payment systems and their identifiers could be received from Payment Aggregator.callbackUrl- URL address of merchant's API that will receive callback.maxAttempts- maximum amount of attempts that Payment Aggregator should perform to deliver callback successfully. Up to 10.isEnabled- boolean value that describes if this URL should be enabled and triggered for now.addSignature- boolean value that describes if Payment Aggregator should send callback signature in header.transactionType- integer value that describes for which types of payments this URL should be triggered. There are three options:1- cash-in (deposit),2- cash-out (withdrawn),null- both.
Callback body is different depending on payment system and transaction type. Bodies and their descriptions of each payment system and payment type are described in another section of current document. If callbacks signing is enabled, Payment Aggregator will sign callback bodies with private key and merchants will be able to validate this signature with provided earlier public key.
Manual transaction data receiving
In case of loosing callback, merchant can manually send request to Aggregator API to get transaction data by its' reference Id. This API endpoint is described below.
Get transaction by reference id
GET
https://{gateway-api-base-url}/api/v1/transactions/{transactionReferenceId}Description: Get transaction data by it's reference Id.
Request:
transactionReferenceId(path) - an unique transaction reference ID that has been assigned by the YaPay's Initialize Transaction endpoint.
Response:
{ "id": int, "transactionReferenceId": GUID string, "providerId": int, "providerName": "string", "merchantId": int, "merchantName": "string", "merchantClientId": int, "accountData": {}, "nonce": "string", "providerTransactionId": "string", "amount": decimal, "currency": "string", "destinationAmount": decimal (nullable), "destinationCurrency": "string", "createdUtc": DateTime, "updatedUtc": DateTime, "transactionType": int, "transactionStatus": int, "transactionStatusMessage": "string", "transactionInternalMessage": "string", "callbackDeliveryStatus": "string", "errorMessage": "string" }id- transaction identifier.transactionReferenceId- GUID for that transaction.providerId- Id of payment system partner.providerName- payment system partner's name.merchantId- merchant's identifier.merchantName- merchant name.merchantClientId- identifier of client from merchant's system.accountData- additional client data from merchant's system.nonce- unique nonce of transaction from merchant's system.providerTransactionId- Id of current transaction, set by payment system.amount- amount of chips to deposit/withdraw.currency- ISO 4217 currency code.destinationAmount- amount of delivered money.destinationCurrency- delivered currency type.createdUtc- UTC time when transaction was created in project's database.updatedUtc- UTC time when transaction was updated last time.transactionType- code of transaction type.1- Deposit,2- Withdrawal.transactionStatus- code of transaction status.0- unknown;1- not confirmed;2- scheduled;3- pending;4- success;-1- cancelled;-1- cancelled;-2- payment system error (money have to be returned);-3- generic payment system error;-4- network error;-5- internal error;-6- falied to validate payment ability.transactionStatusMessage- comment, describing transaction status. Might contain error message, causing stop of processing transaction.transactionInternalMessage- message that should be delivered to merchant client privately.errorMessage- the reason why transaction is failed (if failed)
Error Response:
{ "message": "string" }
Callback structure
Callback
POST
callbackUrl(specified by merchant)Description: Body of callback sent to merchants in case of transaction failure or success.
Request:
{ "id": int, "transactionReferenceId": GUID string, "nonce": "string", "providerId": int, "providerTransactionId": "string", "transactionType": int, "transactionStatus": int, "transactionStatusMessage": "string", "transactionInternalMessage": "string", "clientId": "string", "additionalData": {}, "amount": decimal, "currency": "string", "destinationAmount": decimal, "destinationCurrency": "string", "createdUtc": DateTime, "updatedUtc": DateTime, }id- transaction id on YaPay side.transactionReferenceId- GUID for that transaction.nonce- unique nonce of transaction from merchant's system.providerId- payment system identifier.providerTransactionId- payment system's internal transaction identifier.transactionType- payment type.1- cash-in,2- cash-out.transactionStatus- code of transaction result status.4- success;-1- cancelled;-1- cancelled;-2- payment system error (money have to be returned);-3- generic payment system error;-4- network error;-5- internal error;-6- falied to validate payment ability.transactionStatusMessage- message, describing transaction status.transactionInternalMessage- message that should be delivered to merchant client privately.clientId- id of client from merchant side.additionalData- additional client or merchant data, needed to process transaction.amount- decimal value that describes amount of money that will be deposited or withdrawn.currency- string that contains ISO-code of currency that will be deposited or withdrawn.destinationAmount- amount of delivered money.destinationCurrency- delivered currency type.createdUtc- datetime when transaction was created on payment system.updatedUtc- datetime when transaction was updated on payment system.