Authorisation Request

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 :
  • PENDING - transaction is being processed.
  • DECLINED - transaction failed
  • SUCCEEDED - transaction is successful
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 :
  • FUNDS_RECEIVED - funds are secured
  • FUNDS_MISSING - funds are not secured.

 

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. 

  • mobile
  • desktop
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):
  • [0-9]{10}: Russian mobile phone number (exactly 10 digits).

Example: 1234567890

  • +7[0-9]{10}: Russian mobile phone number using international prefix “+7” and exactly 10 digits mobile phone number.

Example: +71234567890

  • +[0-9]{9, 30}: International mobile phone number, starting with a “+” followed by at least 9 digits.

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 :

  • oneOff - the direct debit is executed once
  • first - first direct debit in a series of recurring ones
sepamodelarecurring sequenceType ASCII M

Sequence type of the direct debit. Possible values:

  • recurring - follow-up direct debit in a series of recurring ones
  • final - last direct debit in a series of recurring direct debits
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:

  • oneOff - the direct debit is executed once
  • first - first direct debit in a series of recurring ones
  • recurring - follow-up direct debit in a series of recurring ones
  • final - last direct debit in a series of recurring direct debits
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.

 

http://{root domain}/api/1/tx/authstatus?merchantId=1234m&txId=92ec1400-5965-4196-9a87-604433365e33&merchantTxId=b49c8898-f8c8-435a-828e-f87f5e

 

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 :

  • PENDING - transaction is being processed.
  • DECLINED - transaction failed
  • SUCCEEDED- transaction is successful

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 :

  • FUNDS_RECEIVED - funds are secured
  • FUNDS_MISSING - funds are not secured.

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" 
}