API documentation

# 5.4 3DS Payments (V1)

There are 2 ways to use 3DS, using AUTH & CHARGE, and using SALE.

# 5.4.1 Auth & charge flow

Flow in 3 easy steps

  1. Make a billing request with AUTH_3DS method
  2. wait for the after3DsComplete event in the wallet to return transaction ID
  3. Make a billing request with CHARGE method using the transction ID received

3DS auth and charge flow


Lets begin,

The 3DS flow starts as regular payment, Make a Billing request where the method is AUTH_3DS .

Note: on sandbox environment, in order start the 3DS flow on the client, the amount and currency should be always 10 GBP

# Request example

curl -X POST \
  https://the-sandbox.mycheckapp.com/wallet/api/v1/billing \
  x-www-form-urlencoded,application/json' \
  -H 'secretKey: <SECRET KEY>' \
  -d 'ccToken=<ccToken>&method=AUTH_3DS&amount=10&currency=GBP&merchantRef=<MERCHANT REF>

# Response example

{
  "transaction": {
    "transactionReference": "10DEC3F1-7735-4CCD-9EF3-990500635AF4",
    "processorData": {
      "AuthoriseAmount": "1000",
      "IsKeyed": "true",
      "ReturnCode": "0",
      "CardNumberLast4": "1001",
      "BIN": "411112",
      "MerchantRef": "DiAen1553772316",
      "CardTypeName": "VISA",
      "RedirectURL": "http://www.mycheck.io",
      "PAReq": "eJxVUdlugzAQ/JUoH4BtQsihjSXnUBupR462ivJmwRaQuGJMBf362iQ07dvOjHd2PQtvsUJcHzGoFXJ4xqqSEQ6ScDFsPjNnxNjIHXLYiQNeOHyhqpIi58yhjgukh6ZNBbHMNQcZXJbbF+7RkU8ZkBuEDNV2zRmlswl1Z0a4EpDLDPkySVG3CiPjJVN0yhRIJ0BQ1LlWLfeZD6QHUKuUx1qXc0LSIpBpXFQaiGWB3DfZ1baqjEuThHw1bsTr6fuj3bjn99P5YckuexVFa7HfLIDYFxBKjdylzKMTOh0wb07Z3DNzOx5kZsdzd+qwifnXFUFph4hesspfBkyoCvOg5bPp2HygR4BNWeRoe4D81kDuK68ebZSBNhkJIVYxChEKsdFPByFcG2snWZ/EJMJ8Ou6MLABim8ntYuR2UVP9u/QPPBynAg==",
      "CardExpiryYYMM": "1912",
      "TxStateText": "3D-Secure Authentication Pending",
      "TxState": "3P",
      "CardType": "VS",
      "Currency": "GBP",
      "MD": "|5.0.0|445|10DEC3F1-7735-4CCD-9EF3-990500635AF4|",
      "TxID": "10DEC3F1-7735-4CCD-9EF3-990500635AF4",
      "ReturnText": "Success",
      "ACSUrl": "https://web2payuat.3cint.com/ipage/service/_2006_05_v1_0_1/test/testacs.aspx",
      "TermUrl": "https://web2payuat.3cint.com/mxg/Service/_2009_11_v5_0_0/CompletePay3DS.aspx"
    },
    "transactionDetails": {
      "transactionReference": "10DEC3F1-7735-4CCD-9EF3-990500635AF4"
    },
    "processorStatus": "APPROVED",
    "status": "OK",
    "processor": "THREEC",
    "source": "MCPCI",
    "orderID": "DiAen1553772316",
    "paymentID": "9aac7890-cf03-4148-8830-ecfb191c2438",
    "amount": "10",
    "transactionID": "ecf4412b-0e9d-4d94-b667-523f0cacb1fd",
    "3ds_confirmation_box_url": "https://web2payuat.3cint.com/ipage/service/_2006_05_v1_0_1/test/testacs.aspx?PAReq=eJxVUdlugzAQ%2FJUoH4BtQsihjSXnUBupR462ivJmwRaQuGJMBf362iQ07dvOjHd2PQtvsUJcHzGoFXJ4xqqSEQ6ScDFsPjNnxNjIHXLYiQNeOHyhqpIi58yhjgukh6ZNBbHMNQcZXJbbF%2B7RkU8ZkBuEDNV2zRmlswl1Z0a4EpDLDPkySVG3CiPjJVN0yhRIJ0BQ1LlWLfeZD6QHUKuUx1qXc0LSIpBpXFQaiGWB3DfZ1baqjEuThHw1bsTr6fuj3bjn99P5YckuexVFa7HfLIDYFxBKjdylzKMTOh0wb07Z3DNzOx5kZsdzd%2BqwifnXFUFph4hesspfBkyoCvOg5bPp2HygR4BNWeRoe4D81kDuK68ebZSBNhkJIVYxChEKsdFPByFcG2snWZ%2FEJMJ8Ou6MLABim8ntYuR2UVP9u%2FQPPBynAg%3D%3D&MD=%7C5.0.0%7C445%7C10DEC3F1-7735-4CCD-9EF3-990500635AF4%7C&TermUrl=http%3A%2F%2F127.0.0.1%3A8011%2Fapi%2Fv1%2F3d-secure%2Fconfirm%3Fsign%3Dd1f54fd2d3c00ac72c0d5eb729700bc0",
    "awaiting_confirmation": 1
  },
  "pm": {
    "id": 39641,
    "source": "MCPCI",
    "issuer_short": "VI",
    "issuer_full": "visa",
    "last_4_digits": "1001",
    "is_single_use": 0,
    "is_short_live": 0,
    "is_capped": 0,
    "is_expired": 0,
    "is_default": 1,
    "metadata": []
  },
  "status": "OK"
}

All 3DS payment response will have payment.awaiting_confirmation = 1

if this the case, you dont make the CHARGE request, you wait for the wallet after3DsComplete callback as described next.

# Wallet integration

listen to after3DsComplete event.

Success example {status: "SUCCESS", transaction_id: "d86ca1b3-5478-4447-a098-516520df06c2"}

Failure example {status: "FAILURE", transaction_id: "ae13a572-7017-4340-8903-c398daf37de5"}

# Charge

Now you can charge this transaction ID and complete the payment.

# Request example

curl -X POST \
  https://the-sandbox.mycheckapp.com/wallet/api/v1/billing \
  x-www-form-urlencoded,application/json' \
  -d 'secretKey=<SECRET KEY>&method=CHARGE&amount=10&currency=GBP&merchantRef=<MERCHANT REF>&transactionID=d86ca1b3-5478-4447-a098-516520df06c2

{
  "transaction": {
    "transactionReference": "B7E493EF-419E-4F24-9419-9B284262DA0F",
    "processorData": {
      "AuthoriseAmount": "1000",
      "ReturnCode": "0",
      "CardNumberLast4": "1103",
      "AuthorisationCode": "135806",
      "MerchantRef": "QkT271553173071",
      "CardTypeName": "VISA",
      "RedirectURL": "http://www.ynet.co.il",
      "CardExpiryYYMM": "1912",
      "CaptureAmount": "1000",
      "TxStateText": "Capture Queued",
      "TxState": "CQ",
      "CardType": "VS",
      "Currency": "GBP",
      "TxID": "B7E493EF-419E-4F24-9419-9B284262DA0F",
      "ReturnText": "APPROVED",
      "AvsResultCode": "Y"
    },
    "transactionDetails": {
      "transactionReference": "B7E493EF-419E-4F24-9419-9B284262DA0F"
    },
    "processorStatus": "APPROVED",
    "status": "OK",
    "processor": "THREEC",
    "source": "MCPCI",
    "orderID": "QkT271553173071",
    "paymentID": "f06ab19e-0b86-4fca-9c32-10907e131318",
    "amount": 10,
    "transactionID": "4d0bb5e3-18fa-48ad-9d4f-0074a6164148"
  },
  "pm": {
    "id": 16221,
    "source": "MCPCI",
    "issuer_short": "VI",
    "issuer_full": "visa",
    "last_4_digits": "1103",
    "is_single_use": 0,
    "is_short_live": 0,
    "is_capped": 0,
    "is_expired": 0,
    "is_default": 1,
    "metadata": []
  },
  "status": "OK"
}

Payment completed, and you can show a success page.



# 5.4.2 Sale flow

Flow in 3 easy steps

  1. Make a billing request with SALE_3DS method
  2. wait for the after3DsComplete event in the wallet to return transaction ID, Shiji will complete the sale request automatically.
  3. Make a request only to verify that the transaction ID you received is valid.

3DS sale flow

# Request example

curl -X POST \
  https://the-sandbox.mycheckapp.com/wallet/api/v1/billing \
  x-www-form-urlencoded,application/json' \
  -H 'secretKey: <SECRET KEY>' \
  -d 'ccToken=<ccToken>&method=SALE_3DS&amount=10&currency=GBP&merchantRef=<MERCHANT REF>

# Response example

{
  "transaction": {
    "transactionReference": "10DEC3F1-7735-4CCD-9EF3-990500635AF4",
    "processorData": {
      "AuthoriseAmount": "1000",
      "IsKeyed": "true",
      "ReturnCode": "0",
      "CardNumberLast4": "1001",
      "BIN": "411112",
      "MerchantRef": "DiAen1553772316",
      "CardTypeName": "VISA",
      "RedirectURL": "http://www.mycheck.io",
      "PAReq": "eJxVUdlugzAQ/JUoH4BtQsihjSXnUBupR462ivJmwRaQuGJMBf362iQ07dvOjHd2PQtvsUJcHzGoFXJ4xqqSEQ6ScDFsPjNnxNjIHXLYiQNeOHyhqpIi58yhjgukh6ZNBbHMNQcZXJbbF+7RkU8ZkBuEDNV2zRmlswl1Z0a4EpDLDPkySVG3CiPjJVN0yhRIJ0BQ1LlWLfeZD6QHUKuUx1qXc0LSIpBpXFQaiGWB3DfZ1baqjEuThHw1bsTr6fuj3bjn99P5YckuexVFa7HfLIDYFxBKjdylzKMTOh0wb07Z3DNzOx5kZsdzd+qwifnXFUFph4hesspfBkyoCvOg5bPp2HygR4BNWeRoe4D81kDuK68ebZSBNhkJIVYxChEKsdFPByFcG2snWZ/EJMJ8Ou6MLABim8ntYuR2UVP9u/QPPBynAg==",
      "CardExpiryYYMM": "1912",
      "TxStateText": "3D-Secure Authentication Pending",
      "TxState": "3P",
      "CardType": "VS",
      "Currency": "GBP",
      "MD": "|5.0.0|445|10DEC3F1-7735-4CCD-9EF3-990500635AF4|",
      "TxID": "10DEC3F1-7735-4CCD-9EF3-990500635AF4",
      "ReturnText": "Success",
      "ACSUrl": "https://web2payuat.3cint.com/ipage/service/_2006_05_v1_0_1/test/testacs.aspx",
      "TermUrl": "https://web2payuat.3cint.com/mxg/Service/_2009_11_v5_0_0/CompletePay3DS.aspx"
    },
    "transactionDetails": {
      "transactionReference": "10DEC3F1-7735-4CCD-9EF3-990500635AF4"
    },
    "processorStatus": "APPROVED",
    "status": "OK",
    "processor": "THREEC",
    "source": "MCPCI",
    "orderID": "DiAen1553772316",
    "paymentID": "9aac7890-cf03-4148-8830-ecfb191c2438",
    "amount": "10",
    "transactionID": "ecf4412b-0e9d-4d94-b667-523f0cacb1fd",
    "3ds_confirmation_box_url": "https://web2payuat.3cint.com/ipage/service/_2006_05_v1_0_1/test/testacs.aspx?PAReq=eJxVUdlugzAQ%2FJUoH4BtQsihjSXnUBupR462ivJmwRaQuGJMBf362iQ07dvOjHd2PQtvsUJcHzGoFXJ4xqqSEQ6ScDFsPjNnxNjIHXLYiQNeOHyhqpIi58yhjgukh6ZNBbHMNQcZXJbbF%2B7RkU8ZkBuEDNV2zRmlswl1Z0a4EpDLDPkySVG3CiPjJVN0yhRIJ0BQ1LlWLfeZD6QHUKuUx1qXc0LSIpBpXFQaiGWB3DfZ1baqjEuThHw1bsTr6fuj3bjn99P5YckuexVFa7HfLIDYFxBKjdylzKMTOh0wb07Z3DNzOx5kZsdzd%2BqwifnXFUFph4hesspfBkyoCvOg5bPp2HygR4BNWeRoe4D81kDuK68ebZSBNhkJIVYxChEKsdFPByFcG2snWZ%2FEJMJ8Ou6MLABim8ntYuR2UVP9u%2FQPPBynAg%3D%3D&MD=%7C5.0.0%7C445%7C10DEC3F1-7735-4CCD-9EF3-990500635AF4%7C&TermUrl=http%3A%2F%2F127.0.0.1%3A8011%2Fapi%2Fv1%2F3d-secure%2Fconfirm%3Fsign%3Dd1f54fd2d3c00ac72c0d5eb729700bc0",
    "awaiting_confirmation": 1
  },
  "pm": {
    "id": 39641,
    "source": "MCPCI",
    "issuer_short": "VI",
    "issuer_full": "visa",
    "last_4_digits": "1001",
    "is_single_use": 0,
    "is_short_live": 0,
    "is_capped": 0,
    "is_expired": 0,
    "is_default": 1,
    "metadata": []
  },
  "status": "OK"
}

All 3DS payment response will have payment.awaiting_confirmation = 1

# Wallet integration

listen to after3DsComplete event.

Success example {status: "SUCCESS", transaction_id: "d86ca1b3-5478-4447-a098-516520df06c2"}

Failure example {status: "FAILURE", transaction_id: "ae13a572-7017-4340-8903-c398daf37de5"}

# 5.4.3 Verify the transaction

GET /wallet/api/v1/transactions/<transaction ID>

# Request example

curl -X GET \
  https://the-sandbox.mycheckapp.com/wallet/api/v1/transactions/43F23E4BDA01154253AD4837A5389A \
  -H 'secretKey: sk_mQSL7FixlpuLJIYM0NS7qPk1c2tbZ'

{
  "transaction": {
    "user_id": 17264,
    "business_id": 1,
    "child_business_id": null,
    "processor": "THREEC",
    "merchant_ref": "528",
    "pm_id": 20425,
    "token": "a870e5eeeccb3b224e5b3bee159f0c301680c8626a93f734b7d124d142304389",
    "external_token": "16a87ea9-7b5a-4172-8a36-534bf9aade95",
    "source": "MCPCI",
    "method": "SALE_3DS",
    "amount": 100,
    "currency": "USD",
    "status": "SUCCESS",
    "transaction_id": "43F23E4BDA01154253AD4837A5389A",
    "order_id": "S9bA31551962549",
    "payment_id": "31136e87-dacb-45d7-877a-3c334fcb28ce",
    "transaction_date": "2019-03-07 12:42:32",
    "ref_transaction_id": "9876DBCA7347014DCAAFFDAE963E36",
    "log": 0,
    "created_at": "2019-03-07 12:42:32",
    "metadata": []
  },
  "status": "OK"
}

Payment completed, and you can show a success page.

← 5.5 3DS payments (PSD2) →