Authorization webhook

Authorization

Delivers authorization requests and outcome confirmations. For an initial decision, approve within 3 seconds using HTTP 200 with status success, or decline using HTTP 403 with status error. HTTP 200 with status error is not a valid decline. The later confirmation shares the authorization id and supplies the response_code actually returned to Mastercard; acknowledge durable receipt with HTTP 200 and status success.

Headers

X-Auth-Token

string

Required

Partner Token

X-Auth-Signature

string

Required

Signature of the request body

X-Auth-Timestamp

string

Required

Request timestamp (Unix Epoch in UTC).

Request body

id

number

Internal (authorization) response ID

rrn

string

Retrieval Reference Number used to find reversals

token_id

string

Card token ID

datetime_authorization

string

Examples:

2023-04-24T12:00:00Z

amount_settlement

number

Authorisation amount in settlement currency

currency_settlement

string

Defaults: EUR

AED

string

AFN

string

ALL

string

AMD

string

ANG

string

AOA

string

ARS

string

AUD

string

AWG

string

AZN

string

BAM

string

BBD

string

BDT

string

BGN

string

BHD

string

BIF

string

BMD

string

BND

string

BOB

string

BOV

string

BRL

string

BSD

string

BTN

string

BWP

string

BYN

string

BZD

string

CAD

string

CDF

string

CHE

string

CHF

string

CHW

string

CLF

string

CLP

string

CNY

string

COP

string

COU

string

CRC

string

CUC

string

CUP

string

CVE

string

CZK

string

DJF

string

DKK

string

DOP

string

DZD

string

EGP

string

ERN

string

ETB

string

EUR

string

FJD

string

FKP

string

GBP

string

GEL

string

GHS

string

GIP

string

GMD

string

GNF

string

GTQ

string

GYD

string

HKD

string

HNL

string

HRK

string

HTG

string

HUF

string

IDR

string

ILS

string

INR

string

IQD

string

IRR

string

ISK

string

JMD

string

JOD

string

JPY

string

KES

string

KGS

string

KHR

string

KMF

string

KPW

string

KRW

string

KWD

string

KYD

string

KZT

string

LAK

string

LBP

string

LKR

string

LRD

string

LSL

string

LYD

string

MAD

string

MDL

string

MGA

string

MKD

string

MMK

string

MNT

string

MOP

string

MRU

string

MUR

string

MVR

string

MWK

string

MXN

string

MXV

string

MYR

string

MZN

string

NAD

string

NGN

string

NIO

string

NOK

string

NPR

string

NZD

string

OMR

string

PAB

string

PEN

string

PGK

string

PHP

string

PKR

string

PLN

string

PYG

string

QAR

string

RON

string

RSD

string

RUB

string

RWF

string

SAR

string

SBD

string

SCR

string

SDG

string

SEK

string

SGD

string

SHP

string

SLL

string

SOS

string

SRD

string

SSP

string

STN

string

SVC

string

SYP

string

SZL

string

THB

string

TJS

string

TMT

string

TND

string

TOP

string

TRY

string

TTD

string

TWD

string

TZS

string

UAH

string

UGX

string

USD

string

USN

string

UYI

string

UYU

string

UYW

string

UZS

string

VES

string

VND

string

VUV

string

WST

string

XAF

string

XCD

string

XOF

string

XPF

string

YER

string

ZAR

string

ZMW

string

ZWL

string

XBT

string

ETH

string

UST

string

USC

string

amount_transaction

number

Authorisation amount in original transaction

currency_transaction

string

Defaults: EUR

AED

string

AFN

string

ALL

string

AMD

string

ANG

string

AOA

string

ARS

string

AUD

string

AWG

string

AZN

string

BAM

string

BBD

string

BDT

string

BGN

string

BHD

string

BIF

string

BMD

string

BND

string

BOB

string

BOV

string

BRL

string

BSD

string

BTN

string

BWP

string

BYN

string

BZD

string

CAD

string

CDF

string

CHE

string

CHF

string

CHW

string

CLF

string

CLP

string

CNY

string

COP

string

COU

string

CRC

string

CUC

string

CUP

string

CVE

string

CZK

string

DJF

string

DKK

string

DOP

string

DZD

string

EGP

string

ERN

string

ETB

string

EUR

string

FJD

string

FKP

string

GBP

string

GEL

string

GHS

string

GIP

string

GMD

string

GNF

string

GTQ

string

GYD

string

HKD

string

HNL

string

HRK

string

HTG

string

HUF

string

IDR

string

ILS

string

INR

string

IQD

string

IRR

string

ISK

string

JMD

string

JOD

string

JPY

string

KES

string

KGS

string

KHR

string

KMF

string

KPW

string

KRW

string

KWD

string

KYD

string

KZT

string

LAK

string

LBP

string

LKR

string

LRD

string

LSL

string

LYD

string

MAD

string

MDL

string

MGA

string

MKD

string

MMK

string

MNT

string

MOP

string

MRU

string

MUR

string

MVR

string

MWK

string

MXN

string

MXV

string

MYR

string

MZN

string

NAD

string

NGN

string

NIO

string

NOK

string

NPR

string

NZD

string

OMR

string

PAB

string

PEN

string

PGK

string

PHP

string

PKR

string

PLN

string

PYG

string

QAR

string

RON

string

RSD

string

RUB

string

RWF

string

SAR

string

SBD

string

SCR

string

SDG

string

SEK

string

SGD

string

SHP

string

SLL

string

SOS

string

SRD

string

SSP

string

STN

string

SVC

string

SYP

string

SZL

string

THB

string

TJS

string

TMT

string

TND

string

TOP

string

TRY

string

TTD

string

TWD

string

TZS

string

UAH

string

UGX

string

USD

string

USN

string

UYI

string

UYU

string

UYW

string

UZS

string

VES

string

VND

string

VUV

string

WST

string

XAF

string

XCD

string

XOF

string

XPF

string

YER

string

ZAR

string

ZMW

string

ZWL

string

XBT

string

ETH

string

UST

string

USC

string

accounts_local

array of object

account_id

number

account_currency

string

Defaults: EUR

AED

string

AFN

string

ALL

string

AMD

string

ANG

string

AOA

string

ARS

string

AUD

string

AWG

string

AZN

string

BAM

string

BBD

string

BDT

string

BGN

string

BHD

string

BIF

string

BMD

string

BND

string

BOB

string

BOV

string

BRL

string

BSD

string

BTN

string

BWP

string

BYN

string

BZD

string

CAD

string

CDF

string

CHE

string

CHF

string

CHW

string

CLF

string

CLP

string

CNY

string

COP

string

COU

string

CRC

string

CUC

string

CUP

string

CVE

string

CZK

string

DJF

string

DKK

string

DOP

string

DZD

string

EGP

string

ERN

string

ETB

string

EUR

string

FJD

string

FKP

string

GBP

string

GEL

string

GHS

string

GIP

string

GMD

string

GNF

string

GTQ

string

GYD

string

HKD

string

HNL

string

HRK

string

HTG

string

HUF

string

IDR

string

ILS

string

INR

string

IQD

string

IRR

string

ISK

string

JMD

string

JOD

string

JPY

string

KES

string

KGS

string

KHR

string

KMF

string

KPW

string

KRW

string

KWD

string

KYD

string

KZT

string

LAK

string

LBP

string

LKR

string

LRD

string

LSL

string

LYD

string

MAD

string

MDL

string

MGA

string

MKD

string

MMK

string

MNT

string

MOP

string

MRU

string

MUR

string

MVR

string

MWK

string

MXN

string

MXV

string

MYR

string

MZN

string

NAD

string

NGN

string

NIO

string

NOK

string

NPR

string

NZD

string

OMR

string

PAB

string

PEN

string

PGK

string

PHP

string

PKR

string

PLN

string

PYG

string

QAR

string

RON

string

RSD

string

RUB

string

RWF

string

SAR

string

SBD

string

SCR

string

SDG

string

SEK

string

SGD

string

SHP

string

SLL

string

SOS

string

SRD

string

SSP

string

STN

string

SVC

string

SYP

string

SZL

string

THB

string

TJS

string

TMT

string

TND

string

TOP

string

TRY

string

TTD

string

TWD

string

TZS

string

UAH

string

UGX

string

USD

string

USN

string

UYI

string

UYU

string

UYW

string

UZS

string

VES

string

VND

string

VUV

string

WST

string

XAF

string

XCD

string

XOF

string

XPF

string

YER

string

ZAR

string

ZMW

string

ZWL

string

XBT

string

ETH

string

UST

string

USC

string

account_amount

number

account_local_rate

number

Authorisation settlement and local currency conversion rate.

fee_amount

number

Combined fees for this local account entry, already included in account_amount. At ATM clearing this includes the separate Fee (ATM fee) and Markup components.

authtype

string

Cash

string

GetContractInfo

string

Goods

string

PaymentCredit

string

PaymentDebit

string

QuasiCash

string

Return

string

Reversal

string

crdacptloc

string

Merchant name

aprvlcode

string

6 alphannumberic approval code.

response_code

string

Aborted

string

Approved

string

ArqcAuthFailed

string

AuthenticationFailed

string

CantFindContract

string

CavvAuthFailed

string

ContractIsRestricted

string

CustTokenInvalidExp

string

Cvv2AuthFailed

string

Cvv2TryExceeded

string

CvvAuthFailed

string

HighRisk

string

InsufficientFunds

string

InvalidCustomer

string

InvalidRequest

string

IssuerLimitHasBeenReached

string

IssuerLimitWillBeExceeded

string

PayeeTokenIsBlocked

string

PinAuthFailed

string

PinTryExceeded

string

Predeclined

string

RecipientTokenNotFound

string

Rejected

string

RoutingError

string

SystemError

string

TimeoutRevNotMatched

string

TokenIsBlocked

string

TokenIsClosed

string

TokenIsCompromised

string

TokenIsDeactivated

string

TokenIsLost

string

TokenIsReferral

string

TokenIsStolen

string

TokenNotFound

string

mcc

number

Merchant category codes

country

string

AA

string

AB

string

AC

string

AD

string

AE

string

AF

string

AG

string

AH

string

AI

string

AJ

string

AK

string

AL

string

AM

string

AN

string

AO

string

AP

string

AQ

string

AR

string

AS

string

AT

string

AU

string

AV

string

AW

string

AX

string

AY

string

AZ

string

BA

string

BB

string

BC

string

BD

string

BE

string

BF

string

BG

string

BH

string

BI

string

BJ

string

BK

string

BL

string

BM

string

BN

string

BO

string

BP

string

BQ

string

BR

string

BS

string

BT

string

BU

string

BV

string

BW

string

BX

string

BY

string

BZ

string

CA

string

CB

string

CC

string

CD

string

CE

string

CF

string

CG

string

CH

string

CI

string

CJ

string

CK

string

CL

string

CM

string

CN

string

CO

string

CP

string

CQ

string

CR

string

CS

string

CT

string

CU

string

CV

string

CW

string

CX

string

CY

string

CZ

string

DA

string

DB

string

DC

string

DD

string

DE

string

DF

string

DG

string

DH

string

DI

string

DJ

string

DK

string

DL

string

DM

string

DN

string

DO

string

DP

string

DQ

string

DR

string

DS

string

DT

string

DU

string

DV

string

DW

string

DX

string

DY

string

DZ

string

EA

string

EB

string

EC

string

ED

string

EE

string

EF

string

EG

string

EH

string

EI

string

EJ

string

EK

string

EL

string

EM

string

EN

string

EO

string

EP

string

EQ

string

ER

string

ES

string

ET

string

EU

string

EV

string

EW

string

EX

string

EY

string

EZ

string

FA

string

FB

string

FC

string

FD

string

FE

string

FF

string

FG

string

FH

string

FI

string

FJ

string

FK

string

FL

string

FM

string

FN

string

FO

string

FP

string

FQ

string

FR

string

FS

string

FT

string

FU

string

FV

string

FW

string

FX

string

FY

string

FZ

string

GA

string

GB

string

GC

string

GD

string

GE

string

GF

string

GG

string

GH

string

GI

string

GJ

string

GK

string

GL

string

GM

string

GN

string

GO

string

GP

string

GQ

string

GR

string

GS

string

GT

string

GU

string

GV

string

GW

string

GX

string

GY

string

GZ

string

HA

string

HB

string

HC

string

HD

string

HE

string

HF

string

HG

string

HH

string

HI

string

HJ

string

HK

string

HL

string

HM

string

HN

string

HO

string

HP

string

HQ

string

HR

string

HS

string

HT

string

HU

string

HV

string

HW

string

HX

string

HY

string

HZ

string

IA

string

IB

string

IC

string

ID

string

IE

string

IF

string

IG

string

IH

string

II

string

IJ

string

IK

string

IL

string

IM

string

IN

string

IO

string

IP

string

IQ

string

IR

string

IS

string

IT

string

IU

string

IV

string

IW

string

IX

string

IY

string

IZ

string

JA

string

JB

string

JC

string

JD

string

JE

string

JF

string

JG

string

JH

string

JI

string

JJ

string

JK

string

JL

string

JM

string

JN

string

JO

string

JP

string

JQ

string

JR

string

JS

string

JT

string

JU

string

JV

string

JW

string

JX

string

JY

string

JZ

string

KA

string

KB

string

KC

string

KD

string

KE

string

KF

string

KG

string

KH

string

KI

string

KJ

string

KK

string

KL

string

KM

string

KN

string

KO

string

KP

string

KQ

string

KR

string

KS

string

KT

string

KU

string

KV

string

KW

string

KX

string

KY

string

KZ

string

LA

string

LB

string

LC

string

LD

string

LE

string

LF

string

LG

string

LH

string

LI

string

LJ

string

LK

string

LL

string

LM

string

LN

string

LO

string

LP

string

LQ

string

LR

string

LS

string

LT

string

LU

string

LV

string

LW

string

LX

string

LY

string

LZ

string

MA

string

MB

string

MC

string

MD

string

ME

string

MF

string

MG

string

MH

string

MI

string

MJ

string

MK

string

ML

string

MM

string

MN

string

MO

string

MP

string

MQ

string

MR

string

MS

string

MT

string

MU

string

MV

string

MW

string

MX

string

MY

string

MZ

string

NA

string

NB

string

NC

string

ND

string

NE

string

NF

string

NG

string

NH

string

NI

string

NJ

string

NK

string

NL

string

NM

string

NN

string

false

string

NP

string

NQ

string

NR

string

NS

string

NT

string

NU

string

NV

string

NW

string

NX

string

NY

string

NZ

string

OA

string

OB

string

OC

string

OD

string

OE

string

OF

string

OG

string

OH

string

OI

string

OJ

string

OK

string

OL

string

OM

string

true

string

OO

string

OP

string

OQ

string

OR

string

OS

string

OT

string

OU

string

OV

string

OW

string

OX

string

OY

string

OZ

string

PA

string

PB

string

PC

string

PD

string

PE

string

PF

string

PG

string

PH

string

PI

string

PJ

string

PK

string

PL

string

PM

string

PN

string

PO

string

PP

string

PQ

string

PR

string

PS

string

PT

string

PU

string

PV

string

PW

string

PX

string

PY

string

PZ

string

QA

string

QB

string

QC

string

QD

string

QE

string

QF

string

QG

string

QH

string

QI

string

QJ

string

QK

string

QL

string

QM

string

QN

string

QO

string

QP

string

QQ

string

QR

string

QS

string

QT

string

QU

string

QV

string

QW

string

QX

string

QY

string

QZ

string

RA

string

RB

string

RC

string

RD

string

RE

string

RF

string

RG

string

RH

string

RI

string

RJ

string

RK

string

RL

string

RM

string

RN

string

RO

string

RP

string

RQ

string

RR

string

RS

string

RT

string

RU

string

RV

string

RW

string

RX

string

RY

string

RZ

string

SA

string

SB

string

SC

string

SD

string

SE

string

SF

string

SG

string

SH

string

SI

string

SJ

string

SK

string

SL

string

SM

string

SN

string

SO

string

SP

string

SQ

string

SR

string

SS

string

ST

string

SU

string

SV

string

SW

string

SX

string

SY

string

SZ

string

TA

string

TB

string

TC

string

TD

string

TE

string

TF

string

TG

string

TH

string

TI

string

TJ

string

TK

string

TL

string

TM

string

TN

string

TO

string

TP

string

TQ

string

TR

string

TS

string

TT

string

TU

string

TV

string

TW

string

TX

string

TY

string

TZ

string

UA

string

UB

string

UC

string

UD

string

UE

string

UF

string

UG

string

UH

string

UI

string

UJ

string

UK

string

UL

string

UM

string

UN

string

UO

string

UP

string

UQ

string

UR

string

US

string

UT

string

UU

string

UV

string

UW

string

UX

string

UY

string

UZ

string

VA

string

VB

string

VC

string

VD

string

VE

string

VF

string

VG

string

VH

string

VI

string

VJ

string

VK

string

VL

string

VM

string

VN

string

VO

string

VP

string

VQ

string

VR

string

VS

string

VT

string

VU

string

VV

string

VW

string

VX

string

VY

string

VZ

string

WA

string

WB

string

WC

string

WD

string

WE

string

WF

string

WG

string

WH

string

WI

string

WJ

string

WK

string

WL

string

WM

string

WN

string

WO

string

WP

string

WQ

string

WR

string

WS

string

WT

string

WU

string

WV

string

WW

string

WX

string

WY

string

WZ

string

XA

string

XB

string

XC

string

XD

string

XE

string

XF

string

XG

string

XH

string

XI

string

XJ

string

XK

string

XL

string

XM

string

XN

string

XO

string

XP

string

XQ

string

XR

string

XS

string

XT

string

XU

string

XV

string

XW

string

XX

string

XY

string

XZ

string

YA

string

YB

string

YC

string

YD

string

YE

string

YF

string

YG

string

YH

string

YI

string

YJ

string

YK

string

YL

string

YM

string

YN

string

YO

string

YP

string

YQ

string

YR

string

YS

string

YT

string

YU

string

YV

string

YW

string

YX

string

YY

string

YZ

string

ZA

string

ZB

string

ZC

string

ZD

string

ZE

string

ZF

string

ZG

string

ZH

string

ZI

string

ZJ

string

ZK

string

ZL

string

ZM

string

ZN

string

ZO

string

ZP

string

ZQ

string

ZR

string

ZS

string

ZT

string

ZU

string

ZV

string

ZW

string

ZX

string

ZY

string

ZZ

string

town

string

Authorisation data town from network

rate

number

Authorisation settlement and original currency conversion rate.

nrn

string

Retrieval Reference Number

advice

boolean

true identifies an authorization advice message. An additional authorization can have advice false and is not then an advice. Read the outcome from response_code and linkage from original references. Identify an existing request outcome confirmation by its repeated id and populated response_code. This flag does not specify delta or replacement-total amount semantics.

tlid

string

Multi-Use Transaction Identification Data

original_authorization_id

string

ID of original Authorization

original_authorization_nrn

string

Retrieval Reference Number of original Authorization

Response

Initial authorization approved, or follow-up outcome durably acknowledged. Declines require HTTP 403.

status

string

Required

success

string

errors

array of string

Defaults:

Error codes list

Example request

curl --request POST \
     --url https://example.com/v1/authorization \
     --header 'X-Auth-Signature: string' \
     --header 'X-Auth-Timestamp: string' \
     --header 'X-Auth-Token: string' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "id": 0,
  "rrn": "string",
  "token_id": "string",
  "datetime_authorization": "2023-04-24T12:00:00Z",
  "amount_settlement": 0.1,
  "currency_settlement": "AED",
  "amount_transaction": 0.1,
  "currency_transaction": "AED",
  "accounts_local": [
    {
      "account_id": 0,
      "account_currency": "AED",
      "account_amount": 0.1,
      "account_local_rate": 0.1,
      "fee_amount": 0.1
    }
  ],
  "authtype": "Cash",
  "crdacptloc": "string",
  "aprvlcode": "string",
  "response_code": "Aborted",
  "mcc": 0,
  "country": "AA",
  "town": "string",
  "rate": 0.1,
  "nrn": "string",
  "advice": true,
  "tlid": "string",
  "original_authorization_id": "string",
  "original_authorization_nrn": "string"
}
'

Example response

{
  "status": "success"
}

Presentment webhook

Built with