Skip to content

Apple™ Pay - Paythru Developer Documentation

1.0 Introduction

Paythru can decrypt Apple Pay card tokens and allow a merchant to process payments for iOS applications. Apple Pay on the web support is still being developed and will be added soon.

The overall process for conducting transactions using Apple Pay is:

  1. The customer, on the merchant's app or website, opts to pay using Apple Pay
  2. The merchant initiates the process directly with Apple, using paythru as your payment gateway and your gatewayMerchantId as supplied by Paythru during boarding
  3. Apple will return to the merchant the encrypted card data
  4. The merchant base64 encodes the encrypted card data prior to sending to Paythru
  5. The merchant forwards this base64 encoded payload to the walletPay method of the Paythru Gateway API for decryption and payment processing

1.1 Card Acceptance

Paythru can accept cards of any type (e.g. Credit, Debit, PrePaid), scheme (e.g. Visa, MasterCard, American Express) or territory which is supported by the connected acquirer.

2.0 Configuration

The developer instructions from Apple are available on their online documentation. You can choose to use Apple Pay with Paythru's Apple Pay certificate or with your own Apple Pay certificate.

2.1 Using Paythru's Apple Pay certificate

  1. If you do not already have one, create an Apple Developer account
  2. Create a merchant identifier to enable your app to use Apple Pay, if you do not already have one
  3. From your Paythru Partner portal, download the Apple Pay certificate signing request (CSR)
  4. Submit the CSR to Apple to create a Payment Processing Certificate. Follow the instructions from Apple, skipping the step of creating the CSR.
  5. Implement Apple Pay in your iOS app, following the guidance on Offering Apple Pay in Your App.
  6. Implement our walletPay method, sending in the encrypted payment token, base64 encoded.

2.2 Using your own Apple Pay certificate

  1. If you do not already have one, create an Apple Developer account
  2. Create a merchant identifier to enable your app to use Apple Pay, if you do not already have one
  3. Create a Payment Processing certificate. Following the instructions from Apple.
  4. Upload the Payment Processing certificate private key to your Paythru Partner portal.
  5. Implement Apple Pay in your iOS app, following the guidance on Offering Apple Pay in Your App.
  6. Implement our walletPay method, sending in the encrypted payment token, base64 encoded.

3.0 Methods

3.1 Wallet Pay method

Description

The wallet pay method is used to request payment on behalf of a customer using a Google or Apple card token.

The result of the transaction is returned in the response from the API. If the transaction could not be processed, an error response will be returned. Optionally, additional parameters may be added to the request. These additional parameters will be recorded against the transaction for reporting and reconciliation purposes.

See the Gateway API documentation for detailed descriptions of endpoint URLs, signing requests, error responses and additional parameters.

Note that the payload parameter needs the encrypted card data received from Google or Apple to be base64 encoded prior to transmission.

URL

/v3/transaction/walletPay

Request parameters

Name Description Format
apiKey* The API Key provided by Paythru used for authentication. Alpha-numeric characters
apiPassword* The API Password provided by Paythru used for authentication. Alpha-numeric characters
payload* The paymentData section of the payload received from Apple Pay, base64 encoded Base64 encoded string
walletType* The type of digital wallet being used (Google or Apple) enum (googlePay or applePay)
threeDSecure Defaults to 0
If set to 1 and Apple payload contains PAN only without authentication details then the response would contain an authentication URL. This URL should be set as the 'src' parameter of a new window or iframe and presented to the customer to complete authentication. Merchants will need to discuss setup with Paythru to allow this.
0/1
returnUrl Required if threeDSecure is set 1. The user will be returned to this URL after the authentication has been completed. URL
paymentType* The type of payment to be processed enum (auth, preauth or verifycard)
shaSignature* The merchant's signature for the request. Please refer to section 2.5 for details of how to construct the signature 128 Alpha numeric characters
terminalKey The terminal key is used by merchants with multiple payment terminals to nominate which terminal should be used for the transaction. This parameter is optional. Alpha numeric characters
itemName0* The name of the 1st item. For additional items, please use itemName1, itemName2 etc. Up to 64 alpha numeric characters
itemPrice0* The price of the 1st item. For additional items, please use itemPrice1, itemPrice2 etc. The value should be specified in the currency's smallest subunit. As examples, 10 US dollars should be specified as 1000 (1000 cents), 5 Pounds Sterling should be specified as 500 (500 pence). The transaction value should therefore be provided in whole numbers only. Integer
itemQuantity0 The quantity of the 1st item. For additional items, please use itemQuantity1, itemQuantity2 etc. If the itemQuantity is not supplied for an item, the quantity will be assumed to be 1 Integer
itemReference0 The reference of the 1st item. For additional items, please use itemReference1, itemReference2 etc. This parameter is optional. Up to 255 characters
currency The ISO 4217 currency (e.g. GBP) that the transaction should be conducted in. Please note that the currency must be enabled on the merchant's account by Paythru. 3 alpha characters
merchantCustomerReference A reference for the merchant to identify the customer. This parameter is optional and can be used for validating the card key Up to 45 characters
merchantReference The merchant's reference for the transaction. The reference will be recorded against the transaction for reporting and reconciliation purposes. This parameter is optional. Up to 32 characters
uniqueMerchantReference A unique merchant's reference. If the same reference value is sent more than once, only the first is processed, all the subsequent requests are rejected. Up to 128 characters
ipAddress IP address of the customer x.x.x.x
Additional fields for MCC 6012 merchants.
mccAccountIdentifier Customer's account number or reference Alpha numeric
mccSurname Customer's surname Alpha characters
mccPostcode Customer's Postcode Alpha numeric characters
mccDateOfBirth Customer's date of birth Numeric characters in the format YYYYMMDD

* denotes a mandatory field

Response parameters

Name Description Format
transactionStatusCode The status code of the transaction 3 numeric characters
transactionStatus The human readable status of the transaction Up to 100 characters
transactionType The human readable type of the transaction Up to 100 characters
transactionKey The unique reference for the transaction generated by Paythru. 32 alpha numeric characters
bank* Supplementary information provided by acquiring bank. A number of response parameters may be returned beginning with 'bank'. These parameters include (but are not limited to):

bankAuthCode (Card issuer's authorisation code)
bankTransId (Transaction ID issued by acquiring bank)
bankResponseCode (Transaction status code issued by acquiring bank)
bankResponseMessage (Transaction status message issued by acquiring bank)
* bankOrderId (Order ID issued by acquiring bank)
Alpha numeric characters and symbols

Example Requests

HTTP Request
apiKey=******************
&apiPassword=******************
&payload=ey...Q==
&walletType=googlePay
&terminalKey=default
&currency=GBP
&itemName0=Baseball Cap
&itemPrice0=500
&shaSignature=c007437ec538a5e09b460a70dd7cfb1b7de83dcec5199dd098e37fc92f8929bbd1402a7251acfd1e6e7dc46eb8cd49a1fced21fb4dcc674464a1183d451ac92e
&paymentType=auth

Example Responses

HTTP Response (XML)
<?xml version="1.0" encoding="utf-8"?>
<paythruResponse>
    <transactionStatusCode>600</transactionStatusCode>
    <transactionStatus>Approved</transactionStatus>
    <transactionType>TokenisedWalletAuth</transactionType>
    <transactionKey>f2085db4024085b4ffc79cbeca463909</transactionKey>
    <bankTransId>10676</bankTransId>
    <bankResponseCode>1</bankResponseCode>
    <bankResponseMessage>OK</bankResponseMessage>
    <bankAuthCode>20200</bankAuthCode>
</paythruResponse>
HTTP Response (JSON)
{
    "transactionStatusCode": 600,
    "transactionStatus": "Approved",
    "transactionType": "TokenisedWalletAuth",
    "transactionKey": "0d39485ae87d7d4ce24561e99316c7b3",
    "bankTransId": "51894",
    "bankResponseCode": "1",
    "bankResponseMessage": "OK",
    "bankAuthCode": "20200"
}
Back to top