Apple Pay Payouts

The Payout request allows credits to be made to a Customer’s Apple Pay account without referencing an original transaction.

You don’t need to reference an original payment or authorisation in order to request a Payout.

APIHosted

The Payout request allows credits to be made to a Customer’s Apple Pay account without referencing an original transaction. There are various stages to performing an Apple Pay payout which need to be completed in your Javascript code as documented by Apple. Once you have checked Apple Pay is available, created an Apple Pay session and validated the merchant you can proceed to making the payout. Once the payout has been authorised Apple will provide the payment token. It will be provided in the Apple SDK event “session.onpaymentauthorized”. This is the token that needs to be put in the payment request to Pay360. To see this in the example below please look at the "paymentMethod"key below.

This is an example of how this could be used with the Apple Pay JavaScript SDK


session. event ) { 
            
    var token = event.payment.token;

    // The function authorise(token) will make an ajax call to the site server, which will in turn call 
    //the Pay360 service /acceptor/rest/transactions/{instId}/payment 
    authorise(token).done( ( response ) => { 
        // determine success by response from merchant server. In this example the response is outcome.status 
        //from the Pay360 api response returned to your server

        var success = "SUCCESS" === response;

        var authorizationResult = {
            status: ( success ? ApplePaySession.STATUS_SUCCESS : ApplePaySession.STATUS_FAILURE ),
            errors: []
        };

        session.completePayment( authorizationResult ); // hides the Apple Pay sheet
		
        if ( success ) { 
	    showConfirmation( response );
        } else {
	    showDecline( data );
        }
    } );
};

API examples

Processing a Payout

POST /acceptor/rest/transactions/{instId}/payout
{
  "transaction": {
    "currency": "GBP",
    "amount": "1000.0",
    "description": "Sample Transaction",
    "merchantRef": "mer_txn_1234556",
    "commerceType": "ECOM",
    "channel": "WEB"
  },
  "paymentMethod": {
    "applepay": {
      "paymentData" : { 
        "version" : "EC_v1",
        "data" : "3+f4oOTwPa6f1UZ6tG...CE=",
        "signature" : "MIAGCSqGSIb3DQ...AAAA==",
        "header": {
          "applicationData" : "DYkwEK...Yu==",
          "ephemeralPublicKey" : "MFkwEK...Md==",
          "publicKeyHash" : "l0CnXdMv...D1I=",
          "transactionId" : "32b...4f3"
        }
      },
      "paymentMethod" : { 
        "displayName" : "Visa 1234",
        "network" : "Visa",
        "type" : "debit"
      },
      "transactionIdentifier" : "32b...4f3"
    }
}

HTTP/1.1 201
{
  "processing": {
    "authResponse": {
      "statusCode": "00",
      "message": "ACQUIRER OK",
      "authCode": "100000",
      "gatewayReference": "5896345970448890-PASS",
      "gatewaySettlement": "2014-10-29",
      "gatewayCode": "0900.000.000",
      "gatewayMessage": "Transaction succeeded",
      "avsAddressCheck": "FULL_MATCH",
      "avsPostcodeCheck": "FULL_MATCH",
      "status": "AUTHORISED"
    },
    "route": "PAYON"
  },
  "paymentMethod": {
    "applepay": {
      "cardType": "VISA_DEBIT",
      "cardUsageType": "DEBIT",
      "cardCategory": "DEBIT",
      "cardScheme": "VISA",
     },
    "billingAddress": {
      "line1": "Flat 1 ",
      "line2": "Cauldron house",
      "line3": "A Street",
      "line4": "Twertonia",
      "city": "Bath",
      "region": "Somerset",
      "postcode": "BA1 234",
      "country": "United Kingdom",
      "countryCode": "GBR"
    },
    "paymentClass": "CARD"
  },
    "billingAddress": {
      "line1": "Flat 1 ",
      "line2": "Cauldron house",
      "line3": "A Street",
      "line4": "Twertonia",
      "city": "Bath",
      "region": "Somerset",
      "postcode": "BA1 234",
      "country": "United Kingdom",
      "countryCode": "GBR"
    },
    "paymentClass": "CARD"
  },
  "transaction": {
    "transactionId": "13501566687",
    "merchantRef": "mer_txn_1234556",
    "status": "SUCCESS",
    "type": "PAYMENT",
    "amount": 1000,
    "consumerSpend": 1000,
    "currency": "GBP",
    "transactionTime": "2014-01-06T12:25:30.902Z",
    "receivedTime": "2014-01-06T12:25:30.902Z",
    "channel": "WEB",
    "customerInitiated": true,
    "stage": "COMPLETE"
  },
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  }
}

API Endpoint

endpoint: /acceptor/rest/transactions/{instId}/payout

method: POST

summary: process Payout

parameters:

instId

string

The installation id

request body:

{
browserInfo {
userAgentHeader	string The Customer’s user agent.
}
sessionId	string Your reference for the Customer’s session.
transaction {	Mandatory
currency	string Mandatory The currency of your Customer’s transaction. Use the 3 character ISO-4217 code.
amount	float Mandatory The amount of your Customer’s transaction.
commerceType	string Mandatory Possible Values: ECOM, MOTO, CA The commerce type for your Customer’s transaction.
channel	string Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER The sales channel for your Customer’s transaction.
merchantRef	string Your reference for the transaction. Max length: 255. It’s recommended that you keep this unique.
deferred	boolean Indicates if you want the Payment to be Authorised and Captured separately.
recurring	boolean Set this field if you want to start a Continuous Authority relationship from this transaction.
description	string The description of the transaction. Maximum length: 255.
}
locale	string The ISO-639-1 code for your Customer’s locale.
customer {
id	string Our ID for the Customer where they are already registered with us.
update	boolean Indicates if you want to update the Customer’s details with the transaction.
email	string Email address for the Customer.
merchantRef	string Conditional Your reference for the Customer. Not required if registered is set to false, mandatory otherwise.
dob	string Date of birth for the Customer.
billingAddress {	The address of the Customer.
line1	string Line 1 of the Customer’s address.
line2	string Line 2 of the Customer’s address.
line3	string Line 3 of the Customer’s address.
line4	string Line 4 of the Customer’s address.
city	string City of the Customer’s address.
region	string Region of the Customer’s address.
postcode	string Post Code of the Customer’s address.
countryCode	string The 3 character ISO-3166-1 code for the Customer’s address country
}
displayName	string Conditional The Customer’s name. Not required if registered is set to false, mandatory otherwise.
telephone	string Telephone number for the Customer.
ip	string The Customer’s IP address.
registered	boolean Indicates if we should register your customer; false if you do not wish to register your customer, otherwise set to true, default value is true.
}
financialServices {	Mandatory for UK/Europe-based MCC 6012/6051/some 7299 merchants
dateOfBirth	string Mandatory for UK/Europe-based MCC 6012/6051/some 7299 merchants Date of birth of the loan recipient, in YYYYMMDD format. For example, for Jan 2nd, 1980, this would be “19800102”.
surname	string Mandatory for UK/Europe-based MCC 6012/6051/some 7299 merchants Surname of the loan recipient; up to six characters, excluding numbers or special characters. If the name is longer than six characters, then provide the first six. For example, for “Smith”, this would be “Smith”; for “Williams”, this would be “Willia”.
accountNumber	string Mandatory for UK/Europe-based MCC 6012/6051/some 7299 merchants Account number used to identify the customer or loan. If this is a PAN, then provide the first six and last four digits of the PAN. Otherwise, provide up to ten characters of the account number.
postCode	string Mandatory for UK/Europe-based MCC 6012/6051/some 7299 merchants First part of the postal code of the loan recipient; up to six characters. For example, if the postal code is “EC2A 1AE”, this would be “EC2A”.
}
transactionOptions {
do3DSecure	boolean Indicates if the transaction should be processed with 3DS. This will override account configuration for 3DS.
sendEmailReceipt	boolean If true, an email receipt will be sent for this transaction. If false, no receipt will be sent. If not present, your account configuration determines if an email is sent.
}
paymentMethod {	Mandatory
applepay {	Mandatory
paymentData {	Mandatory These fields are supplied by the apple pay session object
version	Mandatory string
data	Mandatory string
signature	Mandatory string
header {	Mandatory string
applicationData	Optional string
ephemeralPublicKey	Mandatory string
publicKeyHash	Mandatory string
transactionId	Mandatory string
}
}
paymentMethod {	Mandatory
displayName	Mandatory string
network	Mandatory string
type	Mandatory string
}
transactionIdentifier	Mandatory string
}
registered	boolean Indicates if the supplied payment method should be registered. If no value is supplied true is assumed.
billingAddress {	The billing address of the Customer. We’ll save the billing address when the customer makes their first payment. Providing a billing address for subsequent payments will update the address we’ve saved if you send new, empty or no values for each field.
line1	string Line 1 of the Customer’s billing address.
line2	string Line 2 of the Customer’s billing address.
line3	string Line 3 of the Customer’s billing address.
line4	string Line 4 of the Customer’s billing address.
city	string City of the Customer’s billing address.
region	string Region of the Customer’s billing address.
postcode	string Post Code of the Customer’s billing address.
countryCode	string The 3 character ISO-3166-1 code for the Customer’s billing address country.
}
}
}

response:

{
clientRedirect {	Information about where to send your customer in the case of 3DS or a Callback.
frame	string Possible Values: CONTAINER, TOP The redirect type when the transaction is set to suspend and redirect to a new URL.
pareq	string Returned when the transaction is suspended for 3DS authorisation.
url	string The URL the Customer should be redirected to.
}
fraudGuard {	Information about the Payment.
score	float The score assigned by FraudGuard. Refer to FraudGuard documentation for further details.
geoLocation {
ipCountry {
country	string The three-character ISO code representing the country of origin, determined by the IP address.
ipValues	string Possible Values: PROXY, SATELLITE, EUROPE, APAC Categorisation of the IP address used.
}
ipCity	string The origin city of the transaction request, determined by the IP address.
ipRegion	string The origin state or province of the transaction request, determined by the IP address.
distanceFromIpToBilling	int The physical distance from the billing address to the location determined from the IP address.
}
channelRisk {
freeEmailProvider	boolean Whether or not the email address provided in the transaction request is hosted by a free provider.
openProxyRisk	float A rating of how likely it is that the transaction request originated from behind an open proxy.
}
recentActivity {
last24Hours {
attemptsViaIp	int How many transaction requests have originated from this IP address in the last 24 hours.
attemptsOnCard	int How many transaction requests have used this card in the last 24 hours.
}
}
identityMorphing {
againstAddress	int Measure of identity morphing against the address.
againstEmail	int Measure of identity morphing against the email address.
againstCard	int Measure of identity morphing against the card details.
againstIp	int Measure of identity morphing against the IP address.
}
}
transaction {
transactionId	string Our ID for the transaction.
deferred	boolean Indicates if the Payment capture is deferred.
merchantRef	string Your reference for the transaction.
merchantDescription	string The description of the transaction provided in the request.
status	string Possible Values: SUCCESS, FAILED, PENDING, EXPIRED, CANCELLED, VOIDED The current state of the transaction.
type	string Possible Values: PAYMENT, PREAUTH, PAYOUT, REFUND, CAPTURE, CANCEL, REPEAT, CASH_ISSUE, CASH_PAYMENT Indicates the type of the transaction.
amount	float Indicates the requested amount of the transaction.
consumerSpend	float Indicates the actual amount of the transaction. This will be zero for any type of INITIALIZE transaction, deferred transactions, and rejected transactions.
currency	string Indicates the currency of the transaction. Use the 3 character ISO-4217 code.
transactionTime	string The date and time we processed the transaction in ISO-8601 format.
receivedTime	string The date and time we received the transaction in ISO-8601 format.
commerceType	string Possible Values: ECOM, MOTO, CA The Commerce Type of the transaction.
channel	string Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER The Sales Channel of the transaction.
relatedTransaction {	This field is not applicable for Payments. In case of Refunds it indicates the transaction that was refunded.
transactionId	string Our ID for the transaction that was original.
merchantRef	string Your reference for the transaction that was original.
}
}
processing {	Information about the authorisation status of your transaction.
route	string The name of the processing engine your transaction was submitted to.
voidSuccessful	boolean Indicates if the transaction was voided by a Post Authorisation callback.
authResponse {
statusCode	string The code for the status received from the authoriser, if applicable.
acquirerReference	string The reference received from the authoriser for your transaction, if applicable.
acquirerName	string Name of the authoriser, if applicable.
message	string The message received from the authoriser, if applicable.
authCode	string The code received from the authoriser, if applicable.
gatewayReference	string The reference received from the processing engine.
gatewaySettlement	string The date the processing engine will settle the transaction. in YYYY-MM-DD format.
gatewayCode	string The code for the status received from the processing engine.
gatewayMessage	string The message received from the processing engine.
avsAddressCheck	string Possible Values: NOT_CHECKED, FULL_MATCH, NOT_MATCHED, NOT_PROVIDED Results for the Address Verification checks, if applicable, if applicable.
avsPostcodeCheck	string Possible Values: NOT_CHECKED, FULL_MATCH, NOT_MATCHED, NOT_PROVIDED Results for the PostCode Verification checks, if applicable.
cv2Check	string Possible Values: NOT_CHECKED, MATCHED, NOT_MATCHED Results for the CV2 Verification checks, if applicable.
gatewayStatus	string The status received from the processing engine.
status	string Possible Values: AUTHORISED, DECLINED, REVERSED, REVERSE_FAILED, ERROR The status received from the authoriser, if applicable.
}
}
threeDSecure {	Information about the 3D Secure status of your transaction.
authenticationStatus	string Possible Values: AUTHENTICATED, ATTEMPTED, FAILED, ERROR The status of 3DS authentication check.
authenticationIndicator	string Possible Values: Y, A, N, U The indicator of the 3DS authentication status.
enrolmentDateTime	string The date and time the 3DS enrolment check was performed in ISO-8601 format.
scheme	string The scheme that processed the transaction for 3DS.
eci	string The eCommerce indicator for the transaction.
status	string Possible Values: AUTHENTICATED, BYPASSED, FAILED, NOT_ENROLLED, ENROLMENT_CHECK_FAILURE, INCOMPLETE, NOT_AVAILABLE, NOT_IMPLEMENTED The overall 3DS result for the transaction.
xid	string The ID used during 3DS processing.
enrolmentIndicator	string Possible Values: Y, N, U The indicator of the 3DS enrolment status.
enrolmentStatus	string Possible Values: ENROLLED, NOT_ENROLLED, UNABLE_TO_AUTHENTICATE The status of the 3DS enrolment check.
}
customer {	Information about the Customer.
id	string Our ID for the Customer.
merchantRef	string Your reference for the Customer.
}
financialServices {	Information about the financial services.
dateOfBirth	string The Customer’s date of birth.
surname	string The Customer’s surname.
accountNumber	string The loan account number provided by the merchant, to the Customer.
postCode	string The postal code of the Customer’s billing address.
}
outcome {	Information about the overal outcome of the request.
reasonMessage	string A message indicating the overall outcome of the request. This is where we’ll provide detailed reasons for any errors. In the case of a decline this message can be very general. There can be useful guidance to the cause of the decline in processing.authResponse.gatewayMessage.
status	string Possible Values: SUCCESS, FAILED The overall outcome of the request.
reasonCode	string A code indicating the overall outcome of the request. Refer to Errors for more information.
}
paymentMethod {	Information about the Payment Method used in the request.
applepay {
displayName	string The display name Apple Pay uses for this card (e.g. VISA 1234)
cardType	string information about the type of card used by the Apple Pay transaction
cardUsageType	string The card usage type (credit or debit)
cardScheme	string The card scheme (VISA, Mastercard, Amex, etc)
savedAccountToken	string The token for the card.
}
paymentClass	string The classification of payment method used. Eg. Card, Cash, PayPal
billingAddress {	The billing address of the Customer. Will be used for AVS checks. We’ll save the billing address when the customer makes their first payment. Providing a billing address for subsequent payments will update the address we’ve saved if you send new, empty or no values for each field.
line1	string Line 1 of the Customer’s billing address.
line2	string Line 2 of the Customer’s billing address.
line3	string Line 3 of the Customer’s billing address.
line4	string Line 4 of the Customer’s billing address.
city	string City of the Customer’s billing address.
region	string Region of the Customer’s billing address.
postcode	string Post Code of the Customer’s billing address.
country	string Country name of the Customer’s billing address.
countryCode	string The 3 character ISO-3166-1 code for the Customer’s billing address country.
}
}
}

Hosted examples

Submit a payout


POST /hosted/rest/sessions/{instId}/payouts
{
  "session": {
    "returnUrl": {
      "url": "http://www.example.com/transactionResult?MERCHANTREF=761585761585"
    }
  },
  "transaction": {
    "merchantReference": "761585761585",
    "money": {
      "amount": {
        "fixed": 100
      },
      "currency": "GBP"
    }
  },
  "customer": {
    "identity": {
      "merchantCustomerId": "1111111111111"
    },
    "details": {
      "name": "given1 Family1",
      "address": {
        "line1": "matched",
        "line2": "initialCustomer1AddresssLine2",
        "city": "initalCustomer1City",
        "region": "initalCustomer1Region",
        "postcode": "AVS111",
        "countryCode": "GBR"
      },
      "telephone": "0044111111111",
      "emailAddress": "initialCustomer1@example.com",
      "ipAddress": "1.1.1.1",
      "defaultCurrency": "GBP"
    }
  }
}

HTTP/1.1 201
{
  "sessionId": "38694ada-b151-483e-a325-33df7b46c7be",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/54ed74fb-2bca-47b1-a831-7d8851f5c31f/begin/38694ada-b151-483e-a325-33df7b46c7be",
  "status": "SUCCESS"
}

Hosted Endpoint

endpoint:
/hosted/rest/sessions/{instId}/payouts

method:
POST

summary:
process Payout