atk
    Simplified payment gateway integration
  1. Home
  2. API Docs
  3. atk UI

API Documentation

payer authentication


(excerpt from the payment gateway developer guide)
Payer Authentication: Uses the 3-D Secure protocol in online transactions to verify that payment is coming from the actual cardholder. Most transactions can be authenticated without the customer being aware of the process, but higher risk transactions might require an exchange of one-time passwords (OTPs) during authentication. This authentication of the payer before the transaction is authorized benefits the merchant by shifting chargeback liability from the merchant to the card issuer.

There are two steps to authenticating a payer. Note that, the platform does not require you to send request header information.

  1. A step in which the card information is passed, will return data that is used to build the iframe (JWT Token & Device Data Collection URL)
    2. The values should be used in buildig the iframe for device data collection.

  2. A step in which the shipping address is passed, will either return an authorization response or data that is used to build the challenge iframe (StepUpJWTToken & StepUpURL)
    3. The values should be used in buildig the iframe for challenge validation.
    It may not be required if the authentication was frictionless

Endpoint: https://koroma.co.za/v1/transact

Payload:
  1. channelid - the channel identifier received at successful authentication
  2. clientreferncecode - the payment transaction identifier
  3. cardnumber - the payment card number
  4. cardmonth - two-digit month in which the payment card expires in the format 01/1-12
  5. cardyear - four-digit year in which the payment card expires
  6. cardcvv - card Verification Number
  7. cardamount - order amount (decimals are separated by ".")
  8. cardtype - three-digit value that indicates the card type
Step 1: Payer Authentication SetUp
From the payment journey, this is the step in which you send the payer's card information. You will receive a response with information to be used to build an iframe at the frontend.
  1. The payer authentication setup response will contain a JWT token (consumerAuthenticationInfoAccessToken) and Device Data Collection URL (consumerAuthenticationInfoDDCUrl) to be used in next step
  2. Build a hidden 10 x 10 pixel iframe that is rendered in the browser, and using the access token, you send the customer device data to the device data collection URL (refer to the gateway references)
  3. Proceed to step 2 after receiving the callback response for the form post
 https://koroma.co.za/v1/transact
	
JSON Request
{
    "channelid": "",
    "clientrefcode": "",
    "amount": "",
    "cardnumber": "",
    "cardmonth": "",
    "cardyear": "",
    "cardcvv": "",
    "cardtype": ""
}

JSON Response
{
    "channelid": "",
    "clientReferenceCode": "",
    "id": "",
    "status": "",
    "submitTimeUtc": "",
    "consumerAuthenticationInfoAccessToken": "",
    "consumerAuthenticationInfoDDCUrl": "",
    "consumerAuthenticationInfoReferenceId": "",
    "consumerAuthenticationInfoToken": ""
}


Step 2: Payer Authentication Check Enrolment

This is the step in which you send the payer's shipping information. There are two expected outcomes; frictionless will return an authorization response, and challenge will return a response with information to be used to build an iframe.

You can always use the "Status" field to determine the response type.
Authorization: AUTHORIZED | AUTHORIZED_PENDING_REVIEW
Challenge: PENDING_AUTHENTICATION

Step 2 request with an authorization response, followed by a challenge response: 
 https://koroma.co.za/v1/transact

JSON Request
{
    "channelid": "",
    "clientrefcode": "",
    "referenceid": "",
    "firstname": "",
    "lastname": "",
    "email": "",
    "locality": "",
    "postalcode": ""
}


JSON Response (check enrolment)
{
    "channelid": "",
    "clientReferenceCode": "",
    "id": "",
    "status": "",
    "submitTimeUtc": "",
    "errorInformationReason": "",
    "errorInformationMessage": ".",
    "paymentInformationBin": "",
    "paymentInformationType": "",
    "consumerAuthenticationInfoToken": "",
    "consumerAuthenticationInfoAuthTransactionId": "",
    "consumerAuthenticationInfoSCAOutageExemptionInd": "",
    "consumerAuthenticationInfoVeresEnrolled": "",
    "consumerAuthenticationInfoEcommerceIndicator": "",
    "consumerAuthenticationInfoThreeDSServerTransactionId": "",
    "consumerAuthenticationInfoDirServerTransactionId": "",
    "consumerAuthenticationInfoChallengeRequired": "",
    "consumerAuthenticationInfoAcsTransactionId": "",
    "consumerAuthenticationInfoAcsReferenceNumber": "",
    "consumerAuthenticationInfoAcsOperatorID": "",
    "consumerAuthenticationInfoAcsUrl": "",
    "consumerAuthenticationInfoStepUpUrl": "",
    "consumerAuthenticationInfoPareq": "",
    "consumerAuthenticationInfoParesStatus": "",
    "consumerAuthenticationInfoSpecVersion": ""
}
consumerAuthenticationInfoStepUpUrl and consumerAuthenticationInfoToken are required for building the challenge iframe.

Back to top