Processing

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

Process Payment

POST https://api.zapper.com/v1/payments

Make a new payment against the provided code on behalf of the customer.

Headers

NameTypeDescription

Authorization

String

Bearer <Identity Token> The identity token received from the service account login

x-api-key

string

Authentication Key

Request Body

NameTypeDescription

reference

string

Unique reference for the payment.

currencyISOCode

string

Three character ISO 4217 currency code. Required if non-zapper processed payment.

code

string

Base64 encoded Zapper supported code value.

amount

number

Amount to be paid in cents, excluding tip amount.

tipAmount

number

Tip amount in cents.

customer

object

Details of the customer making the payment.

paymentUTCDate

string

Date of the payment request. Format: yyyy-MM-ddTHH:mm:ss.fffZ

paymentMethod

object

Payment Method for the transaction.

orderReference

string

Unique reference for the invoice used during payment. Mandatory if orderReference was required in decode response.

{
    "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
}

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

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.

Last updated