API documentation

# 5.1 Making payments

With the billing system, you can make different types of action based on the card token, such as sale / refund / etc.. In order to start billing, we must configure a “merchant ref”, this are the credentials of the processor / Gateway you are working with, after it’s configured, you will receive a “merchant_ref”, it’s a unique ID that need to be sent with the transaction

# Request

POST /wallet/api/v1/billing

Form params

name Description Format Required
ccToken The Shiji credit card token received from the client String Yes
method The transaction method, options: SALE, AUTH, CHARGE, REFUND, AUTH_3DS, SALE_3DS String Enum Yes
amount The amount for current transaction Float Yes
currency The currency for current transaction, options: USD, EUR String Enum Yes
merchant_id The ID of the merchant received on the onboarding process int Yes
orderID The ID of the order, if not set, will be auto generated String No
transactionID The ID of the transaction, if not set, will be auto generated String No
metadata A metadata about the transaction, as key-value pairs JSON String No
callback_url Used to update a 3rd party about the success/failure of a payment. Required in case of an Async action such as CHARGE/REFUND/VOID on Adyen. (Payload Example) String No

# Request example:

curl -X POST \
  --url https://the-sandbox.mycheckapp.com/wallet/api/v1/billing \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'secretKey: <SECRET KEY>' \
  --data 'ccToken=<ccToken>&method=AUTH&amount=20&currency=USD&merchant_id=1'

# Request example with metadata:

curl -X POST \
  --url https://the-sandbox.mycheckapp.com/wallet/api/v1/billing \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'secretKey: <SECRET KEY>' \
  --data 'ccToken=<ccToken>&method=AUTH&amount=20&currency=USD&merchant_id=1&metadata={"reservationId":"BAH510004"}'

# Response

{
   "transaction": {
       "status": "OK",
       "authcode": "197415261",
       "tstamp": 1530447532,
       "requestID": "8b5fc869-0c3b-448a-a94b-4a872cb87d9d",
       "processor": "FDATA",
       "source": "MCPCI",
       "orderID": "33456JH4",
       "amount": 20,
       "transactionID": "20CB83A15BB491455D81AF3D09C775"
   },
   "pm": {
       "id": 1,
       "source": "MCPCI",
       "issuer_short": "VI",
       "issuer_full": "visa",
       "last_4_digits": "0026",
       "is_single_use": 0,
       "is_short_live": 0,
       "is_capped": 0,
       "is_expired": 0,
       "is_default": 0,
       "metadata": []
   },
   "status": "OK"
}

# Supported issuer short codes

AMEX => AX
DINERS => DC
DISCOVER => DS
JCB => JB
MAESTRO => TO
MASTERCARD => MC
PAYPAL => PL
TR => TR
UNIONPAY => CU
VISA => VI
APPLEPAY => AP
AMAZONPAY => MWS
GOOGLEPAY => GP

# Moto transaction

A moto transaction is a transaction happened offline on the phone or email. We use the metadata field to mark MOTO transactions

The MOTO flag options:

  • phone
  • email

# Request example:

curl -X POST \
  --url https://the-sandbox.mycheckapp.com/wallet/api/v1/billing \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'secretKey: <SECRET KEY>' \
  --data 'ccToken=<ccToken>&method=AUTH&amount=20&currency=USD&merchant_id=1&metadata={"moto":"phone"}'

# Transaction parameters

There are some transactions that the credit card token is required but not the transactionId,
and vice versa.
On The first time you send the credit card token,
and for response you are getting a transaction ID back.
With this transaction ID you are making the next calls such as AUTH / REFUND without the need of the credit card token Here is table to demonstrate it.

method transactionID ccToken
SALE Required
AUTH Required
CHARGE Required
REFUND Required
SALE_3DS Required
AUTH_3DS Required

# callback_url - Payload Example

This payload will be sent to the specified callback_url as json POST request

{
  "transaction": {
    "user_id": "53579",
    "business_id": "1",
    "processor": "ADYEN_ECOMMERCE",
    "merchant_ref": "3248",
    "pm_id": "22162",
    "token": "0d98bcb8195b055ca017aa0a40d614d2c25bcdf4581d686302e8d97446bdccff",
    "external_token": "cb26b234-fd2f-444e-af55-6d2d0445dac9",
    "source": "MCPCI",
    "method": "CHARGE",
    "amount": "10.00",
    "currency": "USD",
    "status": "SUCCESS",
    "transaction_id": "MCPCI-afde41ba-8dd7-4922-ab72-97ab674c135f",
    "order_id": "K1H5M1603110490",
    "payment_id": "94985656-13ca-4e42-9c59-51ca95f977a9",
    "transaction_date": "2020-10-19 12:28:35",
    "ref_transaction_id": "MCPCI-e8da1579-ff2e-42da-8c9b-cfe857a67097",
    "log": "0",
    "created_at": "2020-10-19 12:28:35",
    "metadata": [
      {
        "key": "callback_url",
        "value": "https://webhook.site/eb145833-1188-4df9-8985-bb2fd4f07bc0"
      },
      {
        "key": "processor_transaction_id",
        "value": "883603110514959E"
      },
      {
        "key": "transactionDetails",
        "value": "{\"currentPspReference\":\"883603110491422A\",\"currentMerchantReference\":\"MCPCI-e8da1579-ff2e-42da-8c9b-cfe857a67097\",\"originalPspReference\":\"883603110491422A\",\"originalMerchantReference\":\"MCPCI-e8da1579-ff2e-42da-8c9b-cfe857a67097\"}"
      }
    ]
  },
  "notification_details": {
    "isSuccess": "1",
    "info": "CHARGE_SUCCEEDED"
  }
}

← 5.2 Update transaction →