logo
API docs by Redocly

Pokkit Score B2B API (1.0.22)

Download OpenAPI specification:Download

E-mail: info@pokkit.co.za License: Apache 2.0

Introduction

The Pokkit Score B2B API handles the registration and maintenance of customers and vouchers.

API Usage

  1. Client ID and Client Secret required for authentication will be provided to you by the Pokkit administrator.
  2. Obtain an access token from the Pokkit authorization server.
  3. Register customers using the /register endpoint.
  4. Submit KYC documents using the /register/kyc endpoint.
  5. Purchase customer vouchers using the /customer/{memberNumber}/vouchers endpoint.
  6. Make voucher payments using the /customer/{memberNumber}/confirm-payment.

Development Environment: https://dev-score.pokkit.io

Registration

Validate Personal Details

Validate personal details as a pre-check

Authorizations:
OAuth2
query Parameters
mobileNumber
required
string
Example: mobileNumber=0823456789
emailAddress
required
string
Example: emailAddress=johndoe@gmail.com

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Validation successful!"
}

Validate ID/Passport Number

Validate ID/Passport number as a pre-check

Authorizations:
OAuth2
query Parameters
idType
required
string
Enum: "RSA_ID" "RSA_CARD" "PASSPORT"
Example: idType=RSA_ID
idNumber
required
string
Example: idNumber=9102938273827

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Validation successful!"
}

Register Customer

Register a new customer on the Pokkit Score system

Authorizations:
OAuth2
Request Body schema: application/json; charset=utf-8
mobileNumber
required
string

The customer's mobile number

password
required
string

SHA-512 hash of the customer's password. Must meet the following policy requirements - At least one digit [0-9], at least one lowercase character [a-z], at least one uppercase character [A-Z], at least one special character, length of at least 8 characters

firstName
required
string

The customer's first name

surname
required
string

The customer's surname

idNumber
required
string

The customer's ID/Passport/Permit Number

idType
required
string (IdType)
Enum: "RSA_ID" "RSA_CARD" "PASSPORT"
required
object (Address)
emailAddress
required
string

The customer's email address

communicationMethod
string (CommunicationMethod)
Enum: "EMAIL" "WHATSAPP" "NONE"
gender
string (Gender)
Enum: "MALE" "FEMALE"
dateOfBirth
string

The customer's date of birth

referralCode
string

Optional referral code

optIn
boolean

Opt in to communication

customerGroupId
integer <int32>

Optional customer group id

object (BankDetails)

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "mobileNumber": "0821231231",
  • "password": "b1582b254ecf552b99f665e0f5da39b0ffeac5d68eb83dccbd2ea159ebe16a7a679f22a241788efb59385ee371687fca283b9af13b61d88b800d685ca5c7b0ff",
  • "firstName": "John",
  • "surname": "Doe",
  • "idNumber": "1234567890987",
  • "idType": "RSA_ID",
  • "homeAddress": {
    },
  • "emailAddress": "johndoe@gmail.com",
  • "communicationMethod": "EMAIL",
  • "gender": "MALE",
  • "dateOfBirth": "1979-07-26",
  • "referralCode": "MYCODE",
  • "optIn": true,
  • "customerGroupId": 1,
  • "bankDetails": {
    }
}

Response samples

Content type
application/json; charset=utf-8
{
  • "status": "SUCCESS",
  • "message": "Registration successful!",
  • "customer": {
    }
}

Submit KYC

Submit KYC documents for the specified memberNumber. Only .png and .jpg file format will be accepted with a maximum of 2mb in size.

Authorizations:
OAuth2
Request Body schema: multipart/form-data
memberNumber
string

The customer's unique Member Number assigned and returned in the registration response.

selfie
string <binary>
selfieFileType
string
Enum: "PNG" "JPG"
idDocument
string <binary>
idDocumentFileType
string
Enum: "PNG" "JPG"
idDocumentBack
string <binary>

Must be supplied if idType is RSA_CARD

idDocumentBackFileType
string
Enum: "PNG" "JPG"

Must be supplied if idType is RSA_CARD

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "KYC upload successful!"
}

Customer

Retrieve Customer

Retrieve customer details for the given memberNumber

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Customer details successfully retrieved!",
  • "customer": {
    }
}

Update Customer

Update customer details for the given memberNumber. Only the following fields are allowed to be edited - emailAddress, mobileNumber, firstName, surname, title, gender, homeAddress, dateOfBirth, maritalStatus

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277
Request Body schema: application/json
memberNumber
required
string

A unique identifier for the customer (This is effectively a Pokkit Member Number)

mobileNumber
string

The customer's 10-digit mobile number

firstName
string

The customer's first name

surname
string

The customer's surname

idType
string (IdType)
Enum: "RSA_ID" "RSA_CARD" "PASSPORT"
idNumber
string

The customer's ID/Passport/Permit Number

title
string (Title)
Enum: "MR" "MRS" "MISS" "MS" "DR" "UNKNOWN"
gender
string (Gender)
Enum: "MALE" "FEMALE"
maritalStatus
string (MaritalStatus)
Enum: "SINGLE" "MARRIED" "WIDOWED" "DIVORCED" "UNKNOWN"
object (Address)
emailAddress
string

The customer's email address

dateOfBirth
string

The member's date of birth

status
string (CustomerStatus)
Enum: "AWAITING_KYC" "PENDING" "ACTIVE" "CANCELLED" "BLOCKED" "INACTIVE"
selfieImage
string

The URL of the customer's selfie image

idImage
string

The URL of the customer's ID image (front)

idImageBack
string

The URL of the customer's ID image (front)

dateRegistered
string

The date/time the customer was registered

dateUpdated
string

The date/time the customer was last updated

communicationMethod
string (CommunicationMethod)
Enum: "EMAIL" "WHATSAPP" "NONE"
object (BankDetails)
imageMatchScore
number

The image match score percentage

groupId
integer <int32>
group
string
monthlyFee
number
minimumVoucherValue
number
maximumVoucherValue
number
redemptionFee
number
earlyRedemptionFee
number
stretchFee
number
easypayNumber
string
easypayBarcode
string
allowedPaymentTypes
string

A comma seperated list of allowed payment types

optIn
boolean

Opt in to communication

Responses

Request samples

Content type
application/json
{
  • "memberNumber": "1234567890",
  • "mobileNumber": "0821231231",
  • "firstName": "John",
  • "surname": "Doe",
  • "idType": "RSA_ID",
  • "idNumber": "1234567890987",
  • "title": "MR",
  • "gender": "MALE",
  • "maritalStatus": "SINGLE",
  • "homeAddress": {
    },
  • "emailAddress": "johndoe@gmail.com",
  • "dateOfBirth": "1979-07-26",
  • "status": "ACTIVE",
  • "selfieImage": "http://example-url/image.png",
  • "idImage": "http://example-url/image.png",
  • "idImageBack": "http://example-url/image.png",
  • "dateRegistered": "2020-11-01 09:12:33",
  • "dateUpdated": "2020-11-01 09:12:33",
  • "communicationMethod": "EMAIL",
  • "bankDetails": {
    },
  • "imageMatchScore": 97.5,
  • "groupId": 0,
  • "group": "string",
  • "monthlyFee": 0,
  • "minimumVoucherValue": 0,
  • "maximumVoucherValue": 0,
  • "redemptionFee": 0,
  • "earlyRedemptionFee": 0,
  • "stretchFee": 0,
  • "easypayNumber": "string",
  • "easypayBarcode": "string",
  • "allowedPaymentTypes": "CARD,CASH",
  • "optIn": true
}

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Customer details successfully updated!",
  • "customer": {
    }
}

Confirm Payment

Confirm payment for customer specified by memberNumber.

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277
Request Body schema: application/json
referenceNumber
required
string

A reference number to link the payment

amount
required
number

The transaction amount

paymentType
required
string (PaymentType)
Enum: "CARD" "CASH" "PAYROLL"
authCode
required
string

Unique authorisation code supplied by Pokkit

Responses

Request samples

Content type
application/json
{
  • "referenceNumber": "string",
  • "amount": 123.55,
  • "paymentType": "CARD",
  • "authCode": "string"
}

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Payment successful!",
  • "amount": 123.55
}

Customer Statement

Generate a statement for customer specified by memberNumber for period specified by startDate and endDate.

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277
query Parameters
startDate
required
string
Example: startDate=2022-10-01
endDate
required
string
Example: endDate=2022-11-01

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Statement successfully generated!",
  • "transactions": [
    ]
}

Customer Vouchers

Retrieve a list of the customer's vouchers for the given memberNumber

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Vouchers successfully retrieved!",
  • "vouchers": [
    ]
}

Add Voucher

Add a voucher to the customer's profile.

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277
Request Body schema: application/json
voucherType
required
string

The selected voucher type

voucherAmount
required
number

The selected voucher amount

voucherTerms
integer <int32>

12 or 24 months

Responses

Request samples

Content type
application/json
{
  • "voucherType": "POKKIT_SCORE",
  • "voucherAmount": 200,
  • "voucherTerms": "12"
}

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Voucher successfully added!",
  • "voucher": {
    }
}

Voucher History

Retrieve the transaction and payment history for a customer's voucher for the given memberNumber and voucherNumber

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277
voucherNumber
required
string
Example: PS221091146743

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Voucher history request successful!",
  • "voucher": {
    },
  • "transactions": [
    ]
}

Verify Redemption

Verify redemption for the given memberNumber and voucherNumber. This MUST be called before /redeem.

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277
voucherNumber
required
string
Example: PS221091146743
query Parameters
redemptionMethod
required
string
Enum: "EFT" "CASH"
Example: redemptionMethod=EFT

The redemption method

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Request successful!",
  • "displayMessage": "Your total investment value is Rx. You will be charge an early redemption fee of R160 which means you will get Rx. Are you sure you wish to proceed?"
}

Redeem Voucher

Redeem voucher for the given memberNumber and voucherNumber

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277
voucherNumber
required
string
Example: PS221091146743
Request Body schema: application/json
voucherNumber
required
string

The unique reference number for the voucher

redemptionMethod
required
string (RedemptionMethod)
Enum: "EFT" "CASH"
reason
required
string

The reason for the redemption, selected from a drop down list or provided as other

Responses

Request samples

Content type
application/json
{
  • "voucherNumber": "123456789",
  • "redemptionMethod": "EFT",
  • "reason": "Cannot afford monthly payment"
}

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Redemption successful!",
  • "displayMessage": "string"
}

Verify Stretch

Verify stretch for the given memberNumber and voucherNumber. This MUST be called before /stretch.

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277
voucherNumber
required
string
Example: PS221091146743
query Parameters
redemptionMethod
required
string
Enum: "EFT" "CASH"
Example: redemptionMethod=EFT

The redemption method

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Request successful!",
  • "displayMessage": "Your total investment value is Rx. You will be charge an early redemption fee of R160 which means you will get Rx. Are you sure you wish to proceed?"
}

Stretch Voucher

Stretch voucher for the given memberNumber and voucherNumber. This feature is only available after every 3 months.

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277
voucherNumber
required
string
Example: PS221091146743
query Parameters
redemptionMethod
required
string
Enum: "EFT" "CASH"
Example: redemptionMethod=EFT

The redemption method

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Stretch successful!",
  • "displayMessage": "string"
}

Check Credit Score

Check customer's credit score history for the given memberNumber

Authorizations:
OAuth2
path Parameters
memberNumber
required
string
Example: 2255832277

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Score successfully retrieved!",
  • "scores": [
    ]
}