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
merchantTxId ASCII Yes Client's Transaction identifier( Generated by Converge 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.
countryCode ASCII Yes 2 letter ISO country code . Merchant location.
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.
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. Converge 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": "1234Merchant",
    "merchantTxId": "b49c8898-f8c8-435a-828e-f87f5e",
    "paymentMethod": "alipay",
    "currencyCode": "GBP",
    "countryCode": "GB",
    "amount": "1200",
    "shopperName": "David Beckham",
    "languageCode": "EN",
    "description": "Buy a car",
    "redirectUrl": "http://google.com",
    "shopperType" : "E_COMMERCE",
    "pushStatusUrl" : "http://localhost:3030/auth",
    "systemId": "123456",
    "payload": {
        "customParam1": "customValue1",
        "customParam2": "customValue2",
        "customParam3": "customValue3"
    }
}

Response

After receiving a transaction authorization request, the PMG returns a response message to the integrators commercial site with the following parameters (again, as in the request message, in the table here only the common parameters for all the payment methods are included and the payment method-specific parameters are described in a separate table later in the document):

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 40 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 or Payment Provider 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 partners. 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

The specific parameters are needed only for some of the LPMs. In the table below there is a description per LPM of the specific parameters that are needed in the request’s payload.

All Parameters are part of payload

Local Payment Method tag 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
safetypay shopperEmail ASCII M Shopper email address.
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
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

Local Payment Method Specific Response Parameters

All Parameters are part of payload

Local Payment Method tag 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.
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)
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)
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