Zapper Platform
Search
K

Processing

Please note the parameters required when Zapper is processing the payment, versus when a third party processor is processing the payment.
post
https://api.zapper.com
/v1/payments
Process Payment

Customer

Field
Type
Description
id
string
Unique identifier for the customer.
countryISOCode
string
optional
Customers country. When information is not provided the customer will be created with a default country of ZA.
firstName
string
Customer first name.
lastName
string
Customer last name.
msisdn
string
optional
Customer phone number.
email
string
optional
Customer email address.
To service our merchants it is recommended that the customer firstName and lastName fields are populated.
These fields assist in allocating and reconciling partner consumer app payments processed over our network.
These details will not and cannot be used for direct marketing given we don’t have the partner consumer app MSISDN.

Payment Method

Field
Type
Description
card
object
conditional
Card details.
external
object
conditional
Third party payment details.
Only one of card or external can be used. When using a card, Zapper will process the payment from the customer's card.
Either CVV or SecureData is required.

Card

Card number

Field
Type
Description
cardNumber
string
Number on the front of the card.
cvv
string
conditional
Security code at the back of the card.
holderName
string
Name on the card.
expiryMonth
number
Month the card expires (1-12).
expiryYear
number
Year the card expires (CCYY).
secureData
object
conditional

Tokenised card

Field
Type
Description
token
string
The token that represents the card.
cvv
string
conditional
Security code at the back of the card.
secureData
object
conditional

Secure Data

Field
Type
Description
enrolled
string
paresStatus
string
eci
string
The relevant ECI indicator.
cavv
string
The Base64 encoded cardholder authentication verification value.
xid
string
The Base64 encoded transaction identifier.
secure3DVersion
string
The 3D Secure version e.g. "2.1.0"
secure3DDirectoryServerTransId
string
Unique identifier for the authenticated transaction assigned by the Directory Server
secure3DAuthenticationType
string
Possible values( not limited) to "01", "02", "03" which correspond to static, dynamic or out-of-band respectively. Must be as generated on completion of the authentication process. indicates the method of authentication used

Enrolled

Value
Description
Y
Yes
N
No
U
Unenrolled

PARes Status

Value
Description
Y
Yes
N
No
U
Unenrolled
A
Anenrolled

External

For non-Zapper processed payments, the external payment method type is be used.
Field
Type
Description
reference
string
Third party payment reference.
status
string
Status of the completed payment. The string is case insensitive.

External Payment Status

Value
Description
success
Successful payment processed.
failed
Failed payment processed.

Example Requests

Card number payment

{
"reference": "00000000-0000-0000-0000-000000000000",
"code":"aHR0cDovLzIuemFwLnBlP3Q9NiZpPTgxNzo0NjM6N1szNHwxMC4wMDoxMFszOXxaQVIsMzh8Q2VudHJhbCBQZXJr",
"amount": 1000,
"tipAmount": 200,
"customer": {
"id": "DEF-456"
},
"paymentUTCDate": "0001-01-01T00:00:00.000Z",
"paymentMethod": {
"card": {
"cardNumber": "4000000000000002",
"cvv": "999",
"holderName": "Card Holder",
"expiryMonth": 9,
"expiryYear": 2030
}
},
"orderReference": "00000000-0000-0000-0000-000000000000"
}

Card number payment using secure data

{
"reference": "00000000-0000-0000-0000-000000000000",
"code":"aHR0cDovLzIuemFwLnBlP3Q9NiZpPTgxNzo0NjM6N1szNHwxMC4wMDoxMFszOXxaQVIsMzh8Q2VudHJhbCBQZXJr",
"amount": 1000,
"tipAmount": 200,
"customer": {
"id": "DEF-456"
},
"paymentUTCDate": "0001-01-01T00:00:00.000Z",
"paymentMethod": {
"card": {
"cardNumber": "4000000000000002",
"holderName": "Card Holder",
"expiryMonth": 9,
"expiryYear": 2030,
"secureData": {
"enrolled": "Y",
"paresStatus": "Y",
"cavv": "Td7wOfSL7kueWouRKPhX883w8ReT",
"xid": "eY4hCbMdj9FQ0X5CV9iQHt2y82T4",
"eci": "05",
"secure3DVersion": "2.1.0",
"secure3DDirectoryServerTransId": "00000000-0000-0000-0000-000000000000",
"secure3DAuthenticationType": "03"
}
}
},
"orderReference": "00000000-0000-0000-0000-000000000000"
}

Tokenised card payment

{
"reference": "00000000-0000-0000-0000-000000000000",
"code":"aHR0cDovLzIuemFwLnBlP3Q9NiZpPTgxNzo0NjM6N1szNHwxMC4wMDoxMFszOXxaQVIsMzh8Q2VudHJhbCBQZXJr",
"amount": 1000,
"tipAmount": 200,
"customer": {
"id": "DEF-456"
},
"paymentUTCDate": "0001-01-01T00:00:00.000Z",
"paymentMethod": {
"card": {
"token": "00000000-0000-0000-0000-000000000000",
"cvv": "999"
}
},
"orderReference": "00000000-0000-0000-0000-000000000000"
}

External (non-Zapper) payment

{
"reference": "bcf12812-affa-42c9-90c8-db65188ff037",
"code":"aHR0cDovLzIuemFwLnBlP3Q9NiZpPTgxNzo0NjM6N1szNHwxMC4wMDoxMFszOXxaQVIsMzh8Q2VudHJhbCBQZXJr",
"amount": 1000,
"tipAmount": 100,
"paymentUTCDate": "0001-01-01T00:00:00.000Z",
"customer": {
"id": "DEF-456"
},
"paymentMethod": {
"external": {
"reference": "12345",
"status": "success"
}
}
"orderReference": "00000000-0000-0000-0000-000000000000"
}

Payment Response

Field
DataType
Description
reference
string
Unique reference of the payment.
invoiceReference
string
Zapper's invoice reference.
invoiceExternalReference
string
Merchant's invoice reference.
merchantName
string
Merchant name.
currencyISOCode
string
The Currency ISO code of the invoice.
invoicedAmount
number
The invoiced amount in cents.
paymentReference
string
Zapper's payment reference (Zapper ID).
paymentUTCDate
string
The date of the payment.
paymentMethodType
string
Payment method type for processing the payment.
paymentMethodDescription
string
The masked value of the payment method.
status
string
The status of the payment.
verificationUrl
string
optional
The URL to invoke additional verification when the status is verificationRequired.
tipAmount
number
The tip amount paid by the customer in cents.
processedAmount
number
The amount processed for the request. Including tip.
customer
object
The customer's first and last name.
siteReference
string
The identifier of the point of sale till. This is required for the routing of Zapper payments and invoices.
errors
array
optional
List of errors related to the transaction.

Payment Status

Value
Description
processing
The transaction is processing.
success
The transaction completed successfully.
failed
The transaction failed during processing.
verificationRequired
The transaction verification. A URL will be returned in the response.

Customer

Field
Datatype
Required
Description
id
string
Yes
The unique reference for the customer.
firstName
string
Yes
The name of the customer.
lastName
string
Yes
The last name of the customer.

Error

Field
Type
Description
errorReference
string
The error identifier.
This value can be quoted when contacting support.
message
string
The message regarding the error.