Checkout Process

The Checkout process consists of several steps which could vary according to the payment gateway the seller uses (only MangoPay supported at the moment).

Each step involves a HTTP request to a SocialPay endpoint with the following headers required:

The initial step requires a user basket with a single product item. And the following steps need some IDs or other data items from the previous steps.

User basket

This basket object is required as the request body to post to the endpoint checkout.

*Required and optional data fields:

Field description
group* Group name on MisGroups
seller_id* Seller ID on SocialPay
item* Product item to buy, see details below
item.name* Product name
item.currency*
item.amount* Amount to pay in pence
buyer* Buyer info, details below
buyer.xid* MisAuth user ID
buyer.first_name
buyer.last_name
buyer.email
buyer.birthday
buyer.country
buyer.nationality
buyer.mobile
buyer.address
  • For new users, all the buyer sub-fields are required.

Example basket:

{
    "group": "12345",
    "seller_id": 13567,
    "item": {
        "name": "product 1",
        "currency": "GBP",
        "amount": 9999
    },
    "buyer": {
        "xid": 12345,
        "first_name": "Adam",
        "last_name": "Alton",
        "email": "adam@makeitsocial.com",
        "birthday": "2000-01-01",
        "country": "GB",
        "nationality": "GB",
        "mobile": "",
        "address": ""
    }
}

1. Checkout

Checkout request starts a new payment process on SocialPay.

  • Request method: POST
  • Headers:
    • X-Api-Key
    • Authorization: JWT ..
    • Content-Type: application/json
  • Path:
    • /v2/checkout
  • Body:
    • basket content as JSON text
  • Response:
    • A status
    • A PayIn ID to be used in the following steps

Post to the checkout endpoint with a user basket.

curl -X POST -d '{"group":"1234",...}' /v2/checkout -H "Content-Type:application/json" -H "X-Api-Key:<..>" -H "Authorization:JWT ..."

Return object:

{
    "status": "OK",
    "payin_id": 1234
}

2. Register a card

Once a PayIn token is created by calling checkout method, it is ready to register a bank card for further payment handling.

This method is required for MangoPay engine, and may not be necessary for other engines to be supported in the future.

The dataset returned successfully should be used to register a card by calling the payment engine, ie, MangoPay, frontend library.

  • Request method: GET
  • Headers:
    • X-Api-Key
    • JWT
  • Path:
    • /v2/payin//regcard
  • Response:
    • Status as "SUCCEEDED" or "FAILED"
    • PreregistrationData if succeeded

Call regcard endpoint to start a card registration process.

curl -X GET https://socialpay.makeitsocial.com/v2/payin/<payin_id>/regcard -H "X-Api-Key:<..>" -H "Authorization:JWT .."

A successful return object:

{
    "Status": "SUCCEEDED",
    "PreregistrationData": "..",
    ...
}

3. Pre-authorise a payment

Once a card ID is obtained after registration, it is ready to pre-authorise a payment against this card.

  • Request method: POST
  • Headers:
    • X-Api-Key
    • JWT
    • Content-Type: application/json
  • Path:
    • /v2/payin//preauth
  • Body:
    • cardId for the registered card ID
  • Response:
    • Status as "SUCCEEDED" or "FAILED"
    • Original object for response from the gateway

Call preauth endpoint to pre-authorise a payment.

curl -X POST -d '{"cardId":".."}' /v2/payin/<payin_id>/preauth -H "X-Api-Key:<..>" -H "Authorization:JWT .."

Return object:

{
    "Status": "SUCCEEDED",
    "Original": {}
}

4. Finalise a pre-authorised payment

After all group members pre-authorised their payments, the group leader can start the finalisation process to actually charge the pre-authorised amount. If the booked product or service offers a group-discount, this is the time to provide a lesser amount by discount.

  • Request method: POST
  • Headers:
    • X-Api-Key
    • JWT
    • Content-Type: application/json
  • Path:
    • /v2/payin//prepay
  • Body:
    • amount optional for a lesser amount
  • Response:
    • Status as "SUCCEEDED" or "FAILED"
    • Original object for response from the gateway

Call prepay endpoint to finalise the payment.

curl -X POST -d '{"amount":99}' /v2/payin/<payin_id>/prepay -H "X-Api-Key:<..>" -H "Authorization:JWT .."

Return object:

{
    "Status": "SUCCEEDED",
    "Original": {}
}

results matching ""

    No results matching ""