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.

Payment Methods - Previous

Card

Payment Details

Last updated 2 months ago

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.

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

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.

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.

Processing

postProcess Payment

Customer

Payment Method

Card

Card number

Tokenised card

Secure Data

Enrolled

PARes Status

External

External Payment Status

Example Requests

Card number payment

Card number payment using secure data

Tokenised card payment

External (non-Zapper) payment

Payment Response

Payment Status

Customer

Error

post
Process Payment