Processing

Please note the parameters required when Zapper is processing the payment, versus when a third party processor is processing the payment.

post
Process Payment

https://api.zapper.com/v1/payments
Make a new payment against the provided code on behalf of the customer.
Request
Response
Request
Headers
Authorization
required
Bearer <Identity Token> The identity token received from the service account login
x-api-key
required
string
Authentication Key
Body Parameters
reference
required
string
Unique reference for the payment.
currencyISOCode
optional
string
Three character ISO 4217 currency code. Required if non-zapper processed payment.
code
required
string
Base64 encoded Zapper supported code value.
amount
required
number
Amount to be paid in cents, excluding tip amount.
tipAmount
optional
number
Tip amount in cents.
customer
required
object
Details of the customer making the payment.
paymentUTCDate
required
string
Date of the payment request. Format: yyyy-MM-ddTHH:mm:ss.fffZ
paymentMethod
required
object
Payment Method for the transaction.
orderReference
optional
string
Unique reference for the invoice used during payment. Mandatory if orderReference was required in decode response.
Response
200: OK
Payment status
{
"reference": "00000000-0000-0000-0000-000000000000",
"invoiceReference": "00000000-0000-0000-0000-000000000000",
"invoiceExternalReference": "00000000-0000-0000-0000-000000000000",
"merchantName": "SyliviaBiller548655",
"currencyISOCode": "ZAR",
"invoicedAmount": 1000,
"paymentReference": "XGKGE3020Q2E8Y4NRD",
"paymentUTCDate": "2020-10-06T00:00:00.0Z",
"paymentMethodType": "Card",
"paymentMethodDescription": "xxxx0002",
"status": "success",
"verificationUrl": null,
"tipAmount": 200,
"processedAmount": 1200,
"customer": {
"id": "00000000-0000-0000-0000-000000000000"
},
"siteReference": "1",
"errors": null
}
302: Found
401: Unauthorized
Identity token invalid.
500: Internal Server Error
Error on the server.

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.

Format: ISO 3166-1 Alpha-2

firstName

string optional

Customer first name.

lastName

string

optional

Customer last name.

msisdn

string

optional

Customer phone number.

email

string

optional

Customer email address.

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

Authenticate security transaction data.

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

Authenticate security transaction data.

Secure Data

Field

Type

Description

enrolled

string

The enrolled status.

paresStatus

string

The PARes status.

eci

string

The relevant ECI indicator.

cavv

string

The Base64 encoded cardholder authentication verification value.

xid

string

The Base64 encoded transaction identifier.

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"
}
}
},
"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.