FX/OG payout

FX/OG payout
  • FX/OG payout uses the same refund approach as it was described earlier.
  • POST data to /invoice/fx_og_refund/{invoice_ref}
  • Process response:
    If view = "redirect" 3D-Secure authentication is needed.
    Otherwise payout is completed for "finished" or failed for "error"
  • Next steps are only needed If view = "redirect"
  • Generate HTML form with values from response (action, method and inputs) and autosubmit it in users browser
  • After completing 3D-Secure authentication user will be redirected to mpi_callback_url with MPI data
    mpi_callback_url is public URL capable of receiving POST requests with MPI data for further sending them to us
  • MPI data needs to be POSTed to /invoice/mpi as described in the next step
  • In response payment_transaction.status will represent the status of payout
Method description
  • Method: POST , URL: /invoice/fx_og_refund/{invoice_ref}
amount M
Payout amount. Decimal point – “.” Two decimal digits available (example: 2000.00). (amount > 0)
There are amount restrictions both for Visa and MasterCard transactions:
Gambling Payment transactions (MasterCard) cannot exceed €50 000
Visa Original Credit Transaction amount cannot exceed $50 000 (€80 000 for Visa Europe transactions)
currency M Payout currency (alphabetic code, example EUR, 3 symbols based on ISO 4217)
Card security code (string). Mandatory for MC + gambling or special configuration in the administration system.
Optional in the other cases
mpi_callback_url Return URL after 3D-Secure (MPI) authentication.
Response fields:
Field Description
Current view for cardholder notification about payment process:
redirect – Merchant must execute cardholder browser redirect to MPI form for further payment authentication;
error – Merchant should notify cardholder about failed payment;
finished – Merchant should notify cardholder about succeeded payment.
action In case of required 3D-Secure authentication, this field will contain URL to submit required data for MPI verification
method In case of required 3D-Secure authentication, this field will contain required HTTP method name to proceed with MPI (GET or POST)
inputs In case of required 3D-Secure authentication, this field will contain additional parameters that should be submitted to "action" URL via "method" method
  • Fields for signature calculation: <invoice_ref><amount><currency><X-Nonce><ShopPassword>
  • The request and response structure are the same as for regular money refund requests and responses.
Request example:
  "amount": "125",
  "csc": "123",
  "mpi_callback_url": "https://merchantsite.example.com/mpi_callback",
  "currency": "EUR"
Response example:
    "invoice": {
    "type": "InvoiceDto",
    "invoice_ref": "gbBzYQaUXEXDpLye1RoGN3Ak5",
    "amount": 55,
    "currency": "EUR",
    "created_date": "2017-07-14T13:23:48.860Z",
    "updated_date": "2017-07-14T13:29:25.613Z",
    "due_date": "2017-07-15T13:23:48.860Z",
    "shop_code": "TEST",
    "invoice_status": "SUCCEEDED",
    "payment_id": "20826681",
    "target_payment_id": null,
    "order_id": "order-22222",
    "error_code": null,
    "error_message": null,
    "payment_method": "FD_FX",
    "merchant_name_a": null,
    "merchant_name_b": null,
    "customer": {},
    "products": [],
    "details": {}
  "payment_transaction": {
    "id": 247211,
    "amount": 125,
    "payment_id": "20826701",
    "target_payment_id": null,
    "currency": "EUR",
    "minor_amount": 12500,
    "created_date": "2017-07-14T13:29:25.559Z",
    "updated_date": "2017-07-14T13:29:25.613Z",
    "transaction_type": "REFUND",
    "status": "SUCCEEDED",
    "error_code": null,
    "error_message": null,
    "shop_code": "TEST",
    "invoice_ref": "gbBzYQaUXEXDpLye1RoGN3Ak5"
  "view": "finished"
3D-secure (MPI) response data submission request parameters
All these parameters will be available in POST request to the mpi_callback_url after customer's 3D-Secure authentication against his card issuing institution/bank. Merchant should pass these fields back to BilderlingsPay to continue any 3D-Secure enrolled card transaction (for MPI-enabled merchant).
  • Method: POST , URL: /invoice/mpi
Field Usage Description
mdErrorMsg M MPI status ("Authenticated" in case of success)
mdStatus M Overall authentication status (number, from 0 to 8, 1 in case of success)
eci M Electronic Commerce Indicator (Visa/MC value)
version M MPI protocol version (2.0)
veresEnrolledStatus M Validation Enrollment status (Y or N)
iReqCode M Code indicating the problem identified in the message
vendorCode M MPI vendor code (usually empty line)
sID M Request session ID (usually "1")
PAResSyntaxOK M Payer Authentication response syntax check status
cavv M Cardholder Authentication Verification Value (ID by VISA)
xid M Upstream provider transaction ID
cavvAlgorithm M Algorithm ID used by VISA
merchantID M Upstream provider merchant ID
iReqDetail M May provide supporting detail, such as the specific data elements that caused the Invalid Request Code
PAResVerified M Payer Authentication response verification mark
txstatus M MPI verification transaction completeness flag (Y or N)
MD M Merchant Data field passed across the MPI requests
paresTxStatus M Payer Authentication transaction Status flag (Y or N)
digest M All previous field signature
  • No signature calculation needed, MPI digest will provide required authentication.
3D-secure (MPI) response data submission request example
  • Method: POST , URL: /invoice/mpi
Request object:
  "mdErrorMsg": "Authenticated",
  "mdStatus": "1",
  "eci": "05",
  "version": "2.0",
  "veresEnrolledStatus": "Y",
  "iReqCode": "",
  "vendorCode": "",
  "sID": "1",
  "PAResSyntaxOK": "true",
  "xid": "E54r1c6KEBgNx8BAWUypDtguv3g=",
  "cavvAlgorithm": "2",
  "merchantID": "3401602",
  "iReqDetail": "",
  "PAResVerified": "true",
  "txstatus": "Y",
  "MD": "OIMf0I42NDW_128NSaAoAEB5g4fefaRbkk8vSk5IRb2b9a5Vs9VRgjfF5faeqjoslQ==",
  "paresTxStatus": "Y",
  "digest": "Ntn94VRLvYLGF2fazEFt5PkoU="