URL: /api/v1/tx/authorization/
METHOD: POST
FORMAT: JSON
DIRECTION: Integrator -> PM Gateway
Request
Request is considered idempotent by following combination of parameters: merchantId + merchantTxId + requestId + systemId
The valid transaction authorisation request should include the mandatory common parameters for each request plus all the mandatory payment method-specific parameters.
In the table below the common parameters for all the payment methods are described and the last parameter “payload” is a JSON string that should contain all the mandatory specific parameters for the chosen payment method (the specific parameters to be included in the JSON are described in an additional table later):
| Parameter Name | Type | Mandatory | Description |
|---|---|---|---|
| requestId | ASCII | Yes | Any Random String/Number generated by the caller. Used for tracing purposes. Allowed characters : [a-zA-Z0-9 -]. Max length 60 symbols. |
| merchantId | ASCII | Yes | Merchant ID in Elavon. Max length is 60 symbol. The merchant should have been configured and active in PMG before sending the transaction authorisation request. The merchant should have also been configured with the payment method of the transaction in order for PMG to be able to process valid requests, otherwise each transaction request will fail at PMG. |
| merchantTxId | ASCII | Yes | Client's Transaction identifier( Generated by ecommerce third-party provider or Terminal). Allowed characters: [a-zA-Z0-9 -]. Max length 30 symbols. |
| paymentMethod | ASCII | Yes | Required local payment method to be used for this transaction. Refer to the list of supported local payment methods. |
| currencyCode | ASCII | Yes | 3-letter ISO currency code of the transaction. The list of the allowed currencies per payment method below (Listofcountry/currencycodesallowedperpaymentmethod). |
| countryCode | ASCII | Yes | 2-letter ISO country code . According to paymnt scheme - shopper location or shopper's payment scheme account location. For some of the payment schemes, only one country code is allowed. For Alipay in Store payment methods, the country code is the merchant's country code. List of allowed country/currency codes per payment method below (Listofcountry/currencycodesallowedperpaymentmethod). |
| amount | ASCII | Yes | The amount to wire in currency's smallest re-presentable unit (e.g., cents). No decimal placeholder. |
| shopperName | UTF-8 | Yes | Shopper Name. 100 characters max length, Minimum 3 characters. For customer present payment methods, a placeholder can be used in the request. |
| shopperType | ASCII | Yes | Shopper type. Refer to supported ShopperTypes. |
| languageCode | ASCII | Yes | Language identifier of the end-user. 2-letter ISO code. |
| description | UTF-8 | No | Description of transaction. Max length 255. |
| redirectUrl | ASCII | No | URL the merchant to be redirected after the transaction success/abort/failure. Max length 255 characters. |
| pushStatusUrl | ASCII | No | URL where transaction status changes will be pushed. If URL is not provided, status changes will not be pushed. |
| systemId | ASCII | Yes | Terminal ID when payment is originated from terminal. Ecommerce third-party provider system id when payment originated from converge. Max length 60. |
| payload | JSON | No | Reserved for addition information to be passed. JSON formatted, key/value String. In general to be used to transfer local payment method specific data. |
Example Request:
JSON Encoded
{
"requestId": "b06c3ecf-8cca-48c6-aeac-7a124eaa6c64",
"merchantId": "testRandomMerchantString",
"merchantTxId": "b49c8898-f8c8-435a-828e-f87f5e",
"paymentMethod": "alipay",
"currencyCode": "GBP",
"countryCode": "GB",
"amount": "1200",
"shopperName": "Shopper Name",
"languageCode": "EN",
"description": "Buy a car",
"redirectUrl": "http://google.com",
"shopperType" : "E_COMMERCE",
"systemId": "123456",
"payload": {
"key": "value",
"key1": "value1",
"key2": "value2"
}
}Response
| Parameter Name | Type | Mandatory | Description |
|---|---|---|---|
| status | ASCII | Yes | Status of Authorization request. One of :
|
| txId | ASCII | Yes | Transaction identifier in Payment Method Gateway. Always a valid transaction identifier is returned. Possible values : [a-zA-Z0-9 -]. Max length 36 symbols. |
| merchantTxId | ASCII | Yes | Value of merchantTxId set in the request. |
| shortTxId | ASCII | No | Short Transaction ID. Min length is 8 digits, max length is 9 digits. Should be used for refund by Terminals. |
| errorMessage | UTF-8 | No | Human readable message, up to 200 characters. Set in case of error code <> ERR_OK |
| error | ASCII | Yes | Error code. Refer to possible error codes for more info. |
| redirectUrl | ASCII | No | URL to redirect the customer. Only available for asynchronous transactions, where the status is PENDING. |
| payload | JSON | No | Key - value JSON structure. Used to set payment type specific parameters. (Refer to Local Payment Method Specific Parameters section.) |
| fundState | ASCII | No | Indicates the funds state, whether they are secured or not. Mandatory in case of status is set to SUCCEEDED. Possible values :
|
Example Response:
JSON Encoded
{
"status": "PENDING",
"txId": "92ec1400-5965-4196-9a87-604433365e33",
"merchantTxId": "b49c8898-f8c8-435a-828e-f87f5e",
"shortTxId" : "123456789",
"error": "ERR_OK",
"redirectUrl": "www.google.com",
"payload": {
"customParam1": "customValue1",
"customParam2": "customValue2"
}
}
Error Codes
In the table below are described all the possible error types that PMG returns on a transaction authorisation request call:
| Error Code | Description |
|---|---|
| ERR_OK | Processing was successful |
| ERR_INPUT | Request parameters doesn't pass required validations |
| ERR_SYSTEM | Unknown error. Transaction failed due to unknown reason |
| ERR_USER_ABORT | Transaction was aborted by user |
| ERR_TIMEOUT | Transaction timed out, while waiting for user action |
| ERR_REMOTE | Transaction processing failed in External Acquirer due to unknown reason |
| ERR_REMOTE_DECLINE | Transaction was declined by remote system due to some limitations (e.g., amount limit) |
| ERR_PAYMENT_METHOD_NOT_SUPPORTED | Requested Local Payment Method is not supported |
HTTP Error Codes
Error Code is always 200. All other error codes should be considered as System errors. Refer to the table above for error codes, encoded as part of the response body.
Supported Shopper Types
| Shopper Type | Description |
|---|---|
| E_COMMERCE | Should be used by eCommerce third-party providers. Identifies payments, which are done online by users. |
| CUSTOMER_PRESENT | Should be used by Terminals. Identifies payments done using POS terminals. |
Local Payment Method Specific Request Parameters
All Parameters are part of payload.
|
Local Payment Method |
Parameter Name |
Type |
Mandatory |
Description |
|---|---|---|---|---|
| alipay | shopperPlatform | ASCII | O |
Used to customize the redirect page and provide better user experience. Possible values.
|
| trustly | shopperId | ASCII | M | Identifier which defines uniquely the shopper. Could be anything - hash, id, email. Preferably to not be any sensitive information, as it will be stored in un-encrypted form. Max length 50 symbols |
| directpay | bic | ASCII | O | BIC of the Bank. If bic parameter is specified, the bank selection page will be bypassed. |
| safetypay | shopperEmail | ASCII | M | Shopper email address. |
| affinbank | shopperEmail | ASCII | M | Shopper email address |
| affinbank | shopperPhone | ASCII | M | Shopper phone number |
| qiwi | shopperMobilePhone | ASCII | M | Phone number identifying the QIWI account to bill. The following formats are supported (in regular expression syntax):
Example: 1234567890
Example: +71234567890
Example: +1234567890 |
| p24 | shopperEmail | ASCII | M | Shopper email address |
| ambank | shopperEmail | ASCII | M | Shopper email address |
| ambank | shopperPhone | ASCII | M | Shopper phone number |
| argencard | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| argencard | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| argencard | shopperEmail | ASCII | M | Shopper email address |
| astropaycard | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| banamex | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| banamex | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| banamex | shopperEmail | ASCII | M | Shopper email address |
| argencard | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| argencard | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| argencard | shopperEmail | ASCII | M | Shopper email address |
| bancodobrasil | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| bancodobrasil | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| bancodobrasil | shopperEmail | ASCII | M | Shopper email address |
| bancodobrasil | shopperAddress | ASCII | M | Shopper address |
| bancodobrasil | shopperZipCode | ASCII | M | Shopper zip code |
| boleto | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| boleto | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| boleto | shopperEmail | ASCII | M | Shopper email address |
| boleto | shopperAddress | ASCII | M | Shopper address |
| boleto | shopperZipCode | ASCII | M | Shopper zip code |
| bradesco | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| bradesco | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| bradesco | shopperEmail | ASCII | M | Shopper email address |
| bradesco | shopperAddress | ASCII | M | Shopper address |
| bradesco | shopperZipCode | ASCII | M | Shopper zip code |
| cabal | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| cabal | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| cabal | shopperEmail | ASCII | M | Shopper email address |
| cencosud | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| cencosud | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| cencosud | shopperEmail | ASCII | M | Shopper email address |
| cimbclicks | shopperPhone | ASCII | M | Shopper phone number |
| cimbclicks | shopperEmail | ASCII | M | Shopper email address |
| dragonpay | shopperPhone | ASCII | M | Shopper phone number |
| dragonpay | shopperEmail | ASCII | M | Shopper email address |
| efecty | shopperEmail | ASCII | M | Shopper email address |
| efecty | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| efecty | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| elo | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| elo | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| elo | shopperEmail | ASCII | M | Shopper email address |
| elo | shopperAddress | ASCII | M | Shopper address |
| elo | shopperZipCode | ASCII | M | Shopper zip code |
| enets |
shopperEmail |
ASCII | M | Shopper email address |
| enets | shopperPhone | ASCII | M | Shopper phone number |
| hipercard | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| hipercard | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| hipercard | shopperEmail | ASCII | M | Shopper email address |
| hipercard | shopperAddress | ASCII | M | Shopper address |
| hipercard | shopperZipCode | ASCII | M | Shopper zip code |
| itau | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| itau | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| itau | shopperEmail | ASCII | M | Shopper email address |
| itau | shopperAddress | ASCII | M | Shopper address |
| itau | shopperZipCode | ASCII | M | Shopper zip code |
| maybanktwou | shopperEmail | ASCII | M | Shopper email address |
| maybanktwou | shopperPhone | ASCII | M | Shopper phone number |
| myclearfpx | shopperEmail | ASCII | M | Shopper email address |
| myclearfpx | shopperPhone | ASCII | M | Shopper phone number |
| naranja | shopperEmail | ASCII | M | Shopper email address |
| naranja | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| naranja | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| nativa | shopperEmail | ASCII | M | Shopper email address |
| nativa | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| nativa | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| oxxo | shopperEmail | ASCII | M | Shopper email address |
| oxxo | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| oxxo | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| paysafecard | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| rhbbank | shopperEmail | ASCII | M | Shopper email address |
| rhbbank | shopperPhone | ASCII | M | Shopper phone number |
| santanderonlinebank | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| santanderonlinebank | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| santanderonlinebank | shopperEmail | ASCII | M | Shopper email address |
| santandercash | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| santandercash | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| santandercash | shopperEmail | ASCII | M | Shopper email address |
| sepapayout | bic | ASCII | M | BIC of the Bank |
| sepapayout | iban | ASCII | M | Valid IBAN of shopper/destination bank |
| tarjetashopping | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| tarjetashopping | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| tarjetashopping | shopperEmail | ASCII | M | Shopper email address |
| webpay | shopperNationalId | ASCII | M | Shopper's national ID (up to 30 characters) |
| webpay | shopperId | ASCII | M | Unique reference identifying the shopper, has to satisfy the following regular expression: [A-Za-z0-9.%,&/+*$-]{1,20} |
| webpay | shopperEmail | ASCII | M | Shopper email address |
| zimpler | shopperEmail | ASCII | M | Shopper email address |
| skrillonetap | shopperEmail | ASCII | M | Shopper email address |
| skrillonetap | consumerId | ASCII | M | Unique id of the shopper. The consumerid has a minimum length of five and a maximum length of 64 letters, allowed characters are [0-9a-zA-Z.,_-] |
| sepamodelafirst | shopperEmail | ASCII | M | Shopper email address |
| sepamodelafirst | iban | ASCII | M | Shopper IBAN addres |
| sepamodelafirst | sequenceType | ASCII | M |
Sequence type of the direct debit. Possible values :
|
| sepamodelarecurring | sequenceType | ASCII | M |
Sequence type of the direct debit. Possible values:
|
| sepamodelarecurring | iban | ASCII | M | Shopper IBAN address |
| sepamodelarecurring | mandatereference | ASCII | M | Mandate reference as returned on the first transaction in the sequence. This is the case when the merchant doesn't handle the mandate. In the first transaction of a sequence of transactions in the PMG initial response of the transaction request this field is included and given to the requesting partner. Each of the recurring transactions after that should include the same value in the request to link the different transactions as sequence under the same mandate |
| sepamodelarecurring | mandatesignaturedate | ASCII | M | Date of the initial transaction, format is YYYY-MM-DD |
| sepamodelarecurring | shopperEmail | ASCII | M | Shopper email address |
| sepamodelc | iban | ASCII | M | Shopper IBAN address |
| sepamodelc | mandatereference | ASCII | M | Mandate reference, managed by the merchant or Elavon. In both cases should be transferred to Payment Method Gateway from Ecommerce third party provider. Has to match [AZa-z0-9:?/+(),.-]{1,35} and shall not start with two slashes (“//”) |
| sepamodelc | mandateUrl | UTF-8 | M | Valid URL pointing to the SEPA mandate, needs to be accessible by Third party payment provider's risk and compliance departments. |
| sepamodelc | mandatesignaturedate | ASCII | M | Date of mandate signature, format is YYYY-MM-DD |
| sepamodelc | sequencetype | M |
Sequence type of the direct debit. Possible values:
|
|
| alipayqr | storeId | ASCII | M | Identifier of the store as boarded with Alipay. May contain only 0-9a-zA-z-_ up to 32 characters |
| alipayqr | storeName | UTF-8 | M | Store name as boarded with Alipay |
| alipaycustomerqr | storeId | ASCII | M | Identifier of the store as boarded with Alipay. May contain only 0-9a-zA-z-_ up to 32 characters |
| alipaycustomerqr | storeName | UTF-8 | M | Store name as boarded with Alipay |
| alipaycustomerqr | shopperDeviceCode | ASCII | M | One-time identification code of the Alipay wallet user as scanned from QR code that is shown by mobile application |
| wechatcustomerqr | wechatShopperDeviceCode | ASCII | M | Authorization code from the Wechat app. Value obtained from scanning the one-time barcode or QR-code from the consumer's device |
| klarna | taxamount | Numeric | M | The total tax amount of the order in the currency’s minor units. |
| klarna | billingaddress | UTF-8 | M | The billing address. Passed as url-encoded serialized JSON string (see Klarna documentation about the billing address). |
| klarna | orderitems | UTF-8 | M | The items being purchased. Passed as url-encoded serialized JSON string (see Klarna documentation about Order Lines) |
| blikpos | code | ASCII | M | T6 or V9 code value for the transaction |
| blikpos | codeType | ASCII | M | The value should be either "T6" or "V9" |
| blikpos | pinBlockType | ASCII | M | The value should always be "ISO-0" (to be sent only when a V9 code is used for authorization (codeType='V9')) |
| blikpos | pinBlock | UTF-8 | M | PIN Block value (to be sent only when a V9 code is used for authorization (codeType='V9')) |
Local Payment Method Specific Response Parameters
All Parameters are part of payload.
|
Local Payment Method |
Parameter Name |
Type |
Mandatory |
Description |
|---|---|---|---|---|
| trustly | userIban | ASCII | The IBAN of the shopper | |
| trustly | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| wechatpay | userCurrency | ASCII | The currency in which the shopper paid. | |
| wechatpay | userAmount | Numeric | The amount paid in userCurrency by the shopper. Via these parameters one can see what the shopper paid in CNY for example, as for We Chat the payment is only presented (cross border) in USD, EUR and other currencies. | |
| directpay | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| directpay | userBankName | ASCII | Name of the bank of the shopper's bank account | |
| directpay | accountHolderName | UTF-8 | Bank Account holder name | |
| directpay | userAccountNumber | ASCII | Bank Account Number of the shopper | |
| directpay | userBankCode | ASCII | Bank code of the shopper's bank account | |
| directpay | userIban | ASCII | The IBAN of the shopper | |
| safetypay | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| qiwi | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| mybank | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| mybank | userBankName | ASCII | Name of the bank of the shopper's bank account | |
| mybank | accountHolderName | UTF-8 | Bank Account holder name | |
| mybank | userAccountNumber | ASCII | Bank Account Number of the shopper | |
| mybank | userBankCode | ASCII | Bank code of the shopper's bank account | |
| mybank | userIban | ASCII | The IBAN of the shopper | |
| ideal | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| ideal | userIban | ASCII | Bank Account Number of the shopper | |
| giropay | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| bancontact | bepurl | ASCII | Trigger URL for mobile payment options in the form BEP://1BC.GIROGATE.DE/BCMC/ 123456789$ICAE3BUIH5P9U53Y5HKA9CRT (contrived example). For more information refer to bancontract integration manual |
|
| bancontact | cardbin | ASCII | BIN of the Bancontact card used (first six digits of the Bancontact card) | |
| bancontact | cardlast4digits | ASCII | Last four digits of the Bancontact card used | |
| bancontact | transactionflow | ASCII | Payment flow of the last attempt, if any. Either ecommerce (card number entry and 3D-Secure), qrcode (payment app triggered through QR code) or urlintent (payment app triggered through URL intent) | |
| astropaycard | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| banamex | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| bancodobrasil | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| boleto | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| bradesco | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| cabal | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| cencosud | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| efecty | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| elo | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| hipercard | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| itau | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| naranja | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| nativa | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| oxxo | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| santanderonlinebank | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| santandercash | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| sepapayout | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| tarjetashopping | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| webpay | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| zimpler | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| argencard | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| sepamodelafirst | mandateReference | UTF-8 | An automatically assigned mandate reference by payment scheme. Returned by PMG to the requesting partner to be used for all the recurring transactions in a sequence under the same mandate | |
| sepamodelafirst | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| sepamodelarecurring | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| sepamodelc | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| alipayqr | qrCode | ASCII | M | QR code value which must be turned into a display image by the POS terminal. Value is a URL like https://qr.alipay.com/bax098035zcce4bd8aly00ee |
| alipaycustomerqr | paymentInfo | UTF-8 | This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar) | |
| wechatqr | wechatQrCode | ASCII | M | QR code value which must be turned into a display image by the POS terminal. Value is a unique URL starting with the weixin:// protocol designation |
| klarna | orderId | ASCII | M | The order ID returned by Klarna after the order has been placed in their system. |
Get Transaction Status
URL : /api/v1/tx/authstatus?merchantId={merchantId}&txId={txId}&merchantTxId={merchantTxId}
METHOD : GET
DIRECTION : Client -> PM Gateway
Request Parameters
|
Parameter Name |
Type |
Mandatory |
Description |
|---|---|---|---|
| merchantId | ASCII |
YES |
Merchant Id in Еlavon. Possible values : [a-zA-Z0-9-]. Max length 16 symbols. |
| txId | ASCII |
YES |
Transaction ID , provided by PM Gateway. Should be always provided if known. Request is considered valid of at least one of txId or merchantTxId is provided. If both are provided txId will be used for locating the transaction. |
| merchantTxId | ASCII | NO | Should be used in very rare cases, when client could not process Authorization response and txId is not known. It is client responsibility to ensure uniqueness of merchantTxId. If txId is not provided, PM Gateway will try to locate the transaction in context of provided merchantId. If more than one transactions are found with the same id, Error will be returned. |
Response Parameters
|
Parameter Name |
Type |
Mandatory |
Description |
|---|---|---|---|
| txId | ASCII |
YES |
Transaction ID in PM Gateway. Always populated. In case of error=ERR_TX_NOT_FOUND or error=ERR_INPUT, no txId is returned |
| merchantTxId | ASCII |
YES |
Merchant transaction ID. In case of error=ERR_TX_NOT_FOUND or error=ERR_INPUT, no merchantTxId is returned |
| shortTxId | ASCII |
YES |
Short transaction ID. Numeric only. Min length 8 digits, Max 9 digits. In case of error=ERR_TX_NOT_FOUND or error=ERR_INPUT, no shortTxId is returned |
| status | ASCII |
YES |
Status of Authorization request. One of :
In case of error=ERR_TX_NOT_FOUND or error=ERR_INPUT, no status is returned |
| fundState | ASCII |
Indicates the funds state,whether they are secured or not. Mandatory in case of status is set to SUCCEEDED. Possible values :
In case of error=ERR_TX_NOT_FOUND or error=ERR_INPUT, no fundState is returned Note : This flow is not relevant for Customer Present (POS) integrations as all such payment methods are GUARANTEED. |
|
| error | ASCII |
YES |
Error code. Refer to possible error codes for more info. |
| errorMessage | UTF-8 |
YES |
Human readable message, up to 200 characters. Set in case of error code <> ERR_OK |
| payload | JSON |
YES |
Key - value json structure. Used to set payment type specific parameters. |
| paymentMethod | ASCII |
YES |
Local payment method used by transaction |
Example Response
{
"txId": "dbc750a8-2b70-43e7-9a7a-1f29eec0942e",
"shortTxId": "00000300",
"merchantTxId": "b49c8898-f8c8-435a-828e-f87f5e",
"status": "PENDING",
"error": "ERR_OK",
"paymentMethod": "alipay"
}Error Codes
All error codes from Authorization Response are valid, in addition the following error codes:
|
ERROR |
Description |
|---|---|
| ERR_TX_NOT_FOUND | Requested transaction is not found in PM Database, or more than one transaction is found with the same merchantTxId. |
HTTP ERRORS
Error Code is always 200. All other error codes should be considered as System errors. Refer to table above for error codes, encoded as part of the response body.
Authorization Status Notification
Once authorization status has been changed, there will be push notification(HTTP POST) to provided HTTP Endpoint by API Consumer. HTTP error code 200 is considered as successful delivery. For any unsuccessful delivery, the notification will be retried for finite number of times, with fixed retry interval. The interval and retry times are subject of PM Gateway configurations. Notification does not contain the final status, therefore consumer is obliged to call Get Refund Status API to retrieve the latest authorization status.
Note : This flow is not relevant for Customer Present (POS) integrations.
METHOD : POST
URL : To be defined as system configuration in PM Gateway
DIRECTION : PM Gateway → Client
Request Parameters
|
Field Name |
Type |
Mandatory |
Description |
|---|---|---|---|
| txId | ASCII |
YES |
PM Gateway transaction ID |
| merchantTxId | ASCII |
YES |
Transaction ID provided by Merchant in Authorization Request |
| merchantId | UTF-8 |
YES |
Merchant ID, provided in Authorization request, |
JSON Encoded
{
"txId": "92ec1400-5965-4196-9a87-604433365e33",
"merchantTxId": "b49c8898-f8c8-435a-828e-f87f5e",
"merchantId": "testRandomMerchantString"
}