QorePay - Api Documentation

Server to Server - Card

Introduction

Server-to-Server ("S2S") integration allows running payments on the server level without direct interaction between the client’s browser or application and API.

You can build an integration that prevents payers from accessing platform resources directly. In this flow, 3D Secure implementation allows API clients to:

Check 3D Secure enrolment, and if the card is enrolled, receive ACS URL together with all the necessary params for redirection to ACS (PaReq, MD); Redirect the payer to the ACS system of their issuer bank; Receive the payer back and execute the authorization with a separate request.

If the card is not enrolled in 3D Secure, authorization will execute synchronously.

Please note that 3DSv2 which is now the industry standard is fully supported by the S2S flow. While PaReq/PaRes below are 3DSv1 parameters (replaced by creq/cres in 3DSv2 challenge), in case of 3DSv2 proxy ACS solution (where the system is accepting the cardholder navigation using 3DSv1 flow and is performing all parts of 3DSv2 verification and challenge on behalf of merchant) is implemented to maintain API compatibility for older integrations.

To accept payments in your application or website via Server to Server integration:

Step 1: Initiate Purchase

Call the /purchases endpoint below to obtain a direct_post_url from the response.

Request	URL
POST	https://gate.qorepay.com/api/v1/purchases/

Remember to specify the success_redirect andfailure_redirect url in the request body.

JSON

 {
    brand_id: '409eb80e-3782-4b1d-afa8-b779759266a5'
    client: {
      email: '[email protected]', 
    },
    purchase: {
      currency: 'NGN',
      products: [
        {
          name: 'Dog food Max',
          quantity: 1, 
          price: 9000
        }
      ], 
    },  
    failure_redirect: 'http://brand.com/failed-payment',
    success_redirect:'http://brand.com/sucess-payment',
  }

Step 2: Create Payment with Card Details

On your server make a POST request to the direct_post_urlappending "?s2s=true" to direct_post_url to form the resulting endpoint:

POST {direct_post_url}?s2s=true

Obtain the S2S token value from your account manager

Request	URL
POST	`{direct_post_url}?s2s=true`

Specify the following headers:

Request Headers


  Content-Type: application/json
  Authorization: Bearer {S2S token}

In the request body, provide the following data in JSON (you can omit some of the fields, then system will use default values; We recommend providing correct values from the user’s browser as it can affect 3D Secure success rate):

Request Headers


{
  "cardholder_name": "John Doe",
  "card_number": "4444333322221111",
  "expires": "01/23",
  "cvc": "123",
  "remember_card": "on",
  "remote_ip": "8.8.8.8",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  "accept_header": "text/html",
  "language": "en-US",
  "java_enabled": false,
  "javascript_enabled": true,
  "color_depth": 24,
  "utc_offset": 0,
  "screen_width": 1920,
  "screen_height": 1080
}

Field	Required	Remarks	Default value
`cardholder_name`	Y	Latin letters only (space and apostrophe ('), dot (.), dash (-) symbols are also allowed), max 30 characters
`card_number`	Y	text, digits only, no whitespace, max 19 characters
`expires`	Y	text in 'MM/YY' format, digits and a slash only (/^d{2}/d{2}$/), max 5 characters
`cvc`	Y	numeric string of 3 or 4 digits
`remember_card`	N	literal value "on" to save card, any other string otherwise
`remote_ip`	Y	external IP of payer’s browser in IPv4 or IPv6 format
`user_agent`	N	User-Agent as sent by the payer’s browser, max 2048 charge	Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/ 537.36 (KHTML, like Gecko) Chrome/ 88.0.4324.96 Safari/ 537.36
`accept_header`	N	Same as above, max 2048 characters	text/html
`language`	N	Same as above, max 8 characters	en-US
`java_enabled`	N	boolean	false
`javascript_enabled`	N	boolean	true
`color_depth`	N	integer in 0-255 range	24
`utc_offset`	N	integer in -32,768 to 32,767 range	0
`screen_width`	N	integer in uint64 range	1920
`screen_height`	N	integer in uint64 range	1080

Step 3: Handle 3DS Not Enrolled

If the card is not enrolled in 3S Secure, then a response will contain the field "status" with one of the following values: "executed" in case of a successful payment authorization; "authorized" in case fund reservation using Purchase.skip_capture was requested; "error" in case of an authorization error.

Example


  {"status": "executed"}

You will receive "executed" or "authorized" statuses with a response status code 200 and "error" status - with a status code of 400.

In all of those cases, it is necessary to set up webhooks for purchase events (purchase.paid, purchase.payment_failure at least) to receive further information about the status of the financial transaction.

If the card is enrolled in 3D Secure, the response will have a status code of 200, the status will be 3DS_required, and the response will contain additional fields:

Example


{
  "status": "3DS_required",
  "Method": "(POST|GET)",
  "PaReq": "...",
  "MD": "... (can arrive empty)",
  "URL": "http://url.of.acs.bank/",
  "callback_url": "https://..."
}

Step 4: Handle 3DS Enrolled

Use the response fields: URL MD andPaReqon your client’s browser submit the following form:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
</head>
<body>
  <form id="form" method="POST" action={{step-2 URL}} >
    <input type="hidden" name="PaReq" value={{step-2 PaReq}}} />
    <input type="hidden" name="MD" value={{step-2 MD}}} />
    <input type="hidden" name="TermUrl" value={{Your URL to receive POST request}} />
  </form>
</body>
<script>
  window.onload = function(){
    document.getElementById("form").submit()
  }
</script>
</html>

This allows the payer to be redirected to the ACS system of their issuer bank.

Create a URL in your system where the payer will be redirected after authorizing the payment through the form. This URL will receive a POST request containing MD and PaRes params in the request body.

The URL in your system should be included in the form above as theTermUrl parameter. The TermUrl parameter is the URL in your system where

Step 5: Complete Authorization

Once the client is back to TermUrl on your server and you have received the MD and PaRes, make a POST request to the callback_url from Step 3 - no auth headers required:

Example


  POST {callback_url from step 3.}

  Content-Type: application/x-www-form-urlencoded
  MD={MD received, if any}&PaRes={PaRes received}

The response will contain the authorization status in JSON format and will be identical to the format described in the previous section.

Visit: Demo Application Implementing S2S Card Payments

To make your integration process easier, we have created a demo application that implements the S2S Card Payments flow. You can find the source code on GitHub.

ON THIS PAGE

Introduction

Initiate purchase

Payment request

No 3DS

Handle 3DS

Complete Authorization

Demo Application