[go: up one dir, main page]
Payments
Developer Documents‣Cards‣Payments

Submit customer payments initiated online or over the phone using the Payment Request. Payments will authorise and capture the funds for settlement in one-step.

The request can additionally be processed with 3D Secure. Configuring your account for 3D Secure can be performed at boarding or at a later date.

APIHosted
API examples
Payment without customer (guest payment)

POST /acceptor/rest/transactions/{instId}/payment
{
    "transaction": {
        "currency": "GBP",
        "amount": "25.00",
        "merchantRef": "TXN-0001",
        "description": "Sample Payment",
        "commerceType": "ECOM"
    },
    "paymentMethod": {
        "card": {
            "pan": "9900000000000010",
            "expiryDate": "1229",
            "cv2": "123",
            "cardHolderName": "John Smith"
        },
        "billingAddress": {
            "line1": "1 Some Street",
            "city": "Metropolis",
            "postcode": "AA1 2BB",
            "countryCode": "GBR"
        }
    }
}

HTTP/1.1 201 Created
{
    "processing": {
        "model": "MANAGE",
        "authResponse": {
            "statusCode": "00",
            "acquirerName": "Barclays Merchant Services",
            "message": "AUTH CODE:116283",
            "authCode": "116283",
            "gatewayReference": "ff67e3fed51e197db4bb1f30e8a20782",
            "gatewayMessage": "AUTH CODE:116283",
            "avsAddressCheck": "FULL_MATCH",
            "avsPostcodeCheck": "FULL_MATCH",
            "cv2Check": "MATCHED",
            "status": "AUTHORISED"
        },
        "route": "CPE"
    },
    "paymentMethod": {
        "registered": false,
        "card": {
            "cardFingerprint": "0hbdt0r/7ofTCqA5qKilqtHeeJg=",
            "new": true,
            "cardType": "MC_DEBIT",
            "cardUsageType": "DEBIT",
            "cardScheme": "MASTERCARD",
            "cardCategory": "DEBIT",
            "maskedPan": "990000******0010",
            "expiryDate": "1229",
            "issuer": "PAY360 TESTING",
            "issuerCountry": "GBR",
            "cardHolderName": "John Smith"
        },
        "billingAddress": {
            "line1": "1 Some Street",
            "city": "Metropolis",
            "postcode": "AA1 2BB",
            "country": "United Kingdom",
            "countryCode": "GBR"
        },
        "paymentClass": "CARD",
        "reuse": {
            "storage": "NONE"
        }
    },
    "customFields": {
        "fieldState": []
    },
    "transaction": {
        "transactionId": "10213520962",
        "merchantRef": "TXN-0001",
        "merchantDescription": "Sample Payment",
        "status": "SUCCESS",
        "stage": "COMPLETE",
        "type": "PAYMENT",
        "amount": 25,
        "consumerSpend": 25,
        "currency": "GBP",
        "transactionTime": "2024-09-02T19:09:43.439+01:00",
        "receivedTime": "2024-09-02T19:09:43.439+01:00",
        "customerInitiated": true
    },
    "outcome": {
        "status": "SUCCESS",
        "reasonCode": "S100",
        "reasonMessage": "Authorised"
    },
    "trace": "T8ily40k8gGYLujOCljwC7g",
    "link": [
        {
            "href": "https://api.mite.pay360.com/acceptor/rest/transactions/5302522/10213520962",
            "rel": "transaction"
        }
    ]
}
Payment saving card for a new customer

POST /acceptor/rest/transactions/{instId}/payment
{
    "transaction": {
        "currency": "GBP",
        "amount": "25.00",
        "merchantRef": "TXN-0002",
        "description": "Sample Payment",
        "commerceType": "ECOM"
    },
    "customer": {
        "merchantRef": "CUST-0001",
        "displayName": "John Smith",
        "email": "john.smith@example.com",
        "telephone": "+441234567890",
        "ip": "185.161.165.20"
    },
    "paymentMethod": {
        "card": {
            "pan": "9902000000000018",
            "expiryDate": "1229",
            "cv2": "123",
            "cardHolderName": "John Smith"
        },
        "billingAddress": {
            "line1": "1 Some Street",
            "city": "Metropolis",
            "postcode": "AA1 2BB",
            "countryCode": "GBR"
        }
    }
}

HTTP/1.1 201 Created
{
    "processing": {
        "model": "MANAGE",
        "authResponse": {
            "statusCode": "00",
            "acquirerName": "Barclays Merchant Services",
            "message": "AUTH CODE:634920",
            "authCode": "634920",
            "gatewayReference": "5f9ad54a83b5ee7a1b35b5302803c2b7",
            "gatewayMessage": "AUTH CODE:634920",
            "avsAddressCheck": "FULL_MATCH",
            "avsPostcodeCheck": "FULL_MATCH",
            "cv2Check": "MATCHED",
            "status": "AUTHORISED"
        },
        "route": "CPE"
    },
    "paymentMethod": {
        "registered": true,
        "card": {
            "cardToken": "MT_QXG4ltszTiyiz1nWbQydnA",
            "cardFingerprint": "l313hfHapXJiLXyROD3X6P75k9E=",
            "new": true,
            "cardType": "VISA_DEBIT",
            "cardUsageType": "DEBIT",
            "cardScheme": "VISA",
            "cardCategory": "DEBIT",
            "maskedPan": "990200******0018",
            "expiryDate": "1229",
            "issuer": "PAY360 TESTING",
            "issuerCountry": "GBR",
            "cardHolderName": "John Smith"
        },
        "billingAddress": {
            "line1": "1 Some Street",
            "city": "Metropolis",
            "postcode": "AA1 2BB",
            "country": "United Kingdom",
            "countryCode": "GBR"
        },
        "paymentClass": "CARD",
        "reuse": {
            "storage": "NEW",
            "agreement": "ADHOC",
            "receivedSchemeReference": "XWM3I9SBV3ORCO"
        }
    },
    "customFields": {
        "fieldState": []
    },
    "customer": {
        "id": "2453687",
        "merchantRef": "CUST-0001"
    },
    "transaction": {
        "transactionId": "10213520965",
        "merchantRef": "TXN-0002",
        "merchantDescription": "Sample Payment",
        "status": "SUCCESS",
        "stage": "COMPLETE",
        "type": "PAYMENT",
        "amount": 25,
        "consumerSpend": 25,
        "currency": "GBP",
        "transactionTime": "2024-09-02T19:22:36.422+01:00",
        "receivedTime": "2024-09-02T19:22:36.422+01:00",
        "customerInitiated": true
    },
    "outcome": {
        "status": "SUCCESS",
        "reasonCode": "S100",
        "reasonMessage": "Authorised"
    },
    "trace": "TBxYU9RS-RyfnP52P9Yh6bw",
    "link": [
        {
            "href": "https://api.mite.pay360.com/acceptor/rest/transactions/5302522/10213520965",
            "rel": "transaction"
        }
    ]
}
Payment using default card for an existing customer

POST /acceptor/rest/transactions/{instId}/payment
{
    "transaction": {
        "currency": "GBP",
        "amount": "25.00",
        "merchantRef": "TXN-0003",
        "description": "Sample Payment",
        "commerceType": "ECOM"
    },
    "customer": {
        "merchantRef": "CUST-0001",
        "ip": "185.161.165.20"
    },
    "paymentMethod": {
        "fromCustomer": {
            "cv2": "123"
        }
    }
}

HTTP/1.1 201 Created
{
    "processing": {
        "model": "MANAGE",
        "authResponse": {
            "statusCode": "00",
            "acquirerName": "Barclays Merchant Services",
            "message": "AUTH CODE:572009",
            "authCode": "572009",
            "gatewayReference": "a689a7919a629904ddd164209ba78894",
            "gatewayMessage": "AUTH CODE:572009",
            "avsAddressCheck": "FULL_MATCH",
            "avsPostcodeCheck": "FULL_MATCH",
            "cv2Check": "MATCHED",
            "status": "AUTHORISED"
        },
        "route": "CPE"
    },
    "paymentMethod": {
        "registered": true,
        "card": {
            "cardToken": "MT_QXG4ltszTiyiz1nWbQydnA",
            "cardFingerprint": "l313hfHapXJiLXyROD3X6P75k9E=",
            "new": false,
            "cardType": "VISA_DEBIT",
            "cardUsageType": "DEBIT",
            "cardScheme": "VISA",
            "cardCategory": "DEBIT",
            "maskedPan": "990200******0018",
            "expiryDate": "1229",
            "issuer": "PAY360 TESTING",
            "issuerCountry": "GBR",
            "cardHolderName": "John Smith"
        },
        "billingAddress": {
            "line1": "1 Some Street",
            "city": "Metropolis",
            "postcode": "AA1 2BB",
            "country": "United Kingdom",
            "countryCode": "GBR"
        },
        "paymentClass": "CARD",
        "reuse": {
            "storage": "EXISTING",
            "agreement": "ADHOC",
            "originalSchemeReference": "XWM3I9SBV3ORCO",
            "receivedSchemeReference": "699VJDIILOHYP4"
        }
    },
    "customFields": {
        "fieldState": []
    },
    "customer": {
        "id": "2453687",
        "merchantRef": "CUST-0001"
    },
    "transaction": {
        "transactionId": "10213520966",
        "merchantRef": "TXN-0003",
        "merchantDescription": "Sample Payment",
        "status": "SUCCESS",
        "stage": "COMPLETE",
        "type": "PAYMENT",
        "amount": 25,
        "consumerSpend": 25,
        "currency": "GBP",
        "transactionTime": "2024-09-02T19:26:25.953+01:00",
        "receivedTime": "2024-09-02T19:26:25.953+01:00",
        "customerInitiated": true
    },
    "outcome": {
        "status": "SUCCESS",
        "reasonCode": "S100",
        "reasonMessage": "Authorised"
    },
    "trace": "TPUoVKGedfrLUvFZCiTKB1Q",
    "link": [
        {
            "href": "https://api.mite.pay360.com/acceptor/rest/transactions/5302522/10213520966",
            "rel": "transaction"
        }
    ]
}
API Endpoint
endpoint: /acceptor/rest/transactions/{instId}/payment
method: POST
summary: process Payment

parameters:

Name
Data Type
Description
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 recurring Continuous Authority relationship from this transaction.
instalment boolean
Set this field if you want to start an instalment Continuous Authority relationship from this transaction.
description string
The description of the transaction. Maximum length: 255.
continuousAuthorityAgreement { Conditional
The continuous authority agreement established with the cardholder. Required if you want to process a transaction initiating a recurring or instalment series using 3DSv2
minFrequency integer
Mandatory
Minimum number of days expected between payments in a recurring or instalment sequence. Must be >= 1.
expiry string
Mandatory
Date (YYYY-MM-DD) at which recurring/instalment agreement expires, or at which it will need to be re-authenticated in order to continue. Must be in the future.
numberOfInstalments integer
Conditional
Total number of payments in an instalment sequence – including this one, if starting with a payment. Required only for instalments; must be >= 2.
}
}
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. For best results, use international format, e.g. “+441234567890”.
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 {

Supplementary data for Financial Services payments, including loan repayments and other credit-related activities.

UK- and Europe-based merchants with merchant category code (MCC) 6012, and some merchants coded MCC 6051 or MCC 7299, are required to provide this information about the primary recipient, who may be different from the customer making payment. Consult your acquirer if you are not sure whether you should submit this.

Cannot be submitted in conjunction with accountFunding.
dateOfBirth string
Date of birth of the recipient, in YYYYMMDD format. For example, for Jan 2nd, 1980, this would be “19800102”.
surname string
Surname/family name of the 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
Account number used to identify the recipient 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
First part of the recipient’s postal code; up to six characters. For example, if the postal code is “LE11 3QF”, this would be “LE11”.
}
accountFunding {

Supplementary data for Account Funding Transactions (AFT), e.g. money transfers. You should provide this if advised by your acquirer.

Cannot be submitted in conjunction with financialServices.
recipient { Details about the funding recipient
givenName string
Recipient’s given name
surname string
Recipient’s surname/family name
address string
Recipient’s address (house/building name and number, street/road name, etc.)
city string
Recipient city
state string
Only for recipients based in the US or Canada
Recipient state/province code (2-3 characters), e.g. “CA”, “DE”, “MD”, “TN” et al. in the US; “AB”, “ON”, “QC”, “SK” et al. in Canada
countryCode string
Recipient country code (ISO-3166-alpha-3), e.g. “CAN”, “GBR”, “USA” et al.
}
}
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
fromCustomer { Mandatory
Use if you want to use your Customer’s default card. This section is mandatory if you are not providing a token or full card details.
cv2 string
The Customer’s Card Security Code (CSC, CV2, CVV).
}
registered boolean
Indicates if the supplied card payment method should be registered. If no value is supplied true is assumed. This field will not be accepted for non-card payment
methods.
card { Mandatory
Use if you want to provide your Customer’s card details. This section is mandatory if you are not providing a token (merchant or CardLock) or details of the Customer’s default card.
pan string
Mandatory
The card number.
cv2 string
The Card Security Code (CSC, CV2, CVV).
expiryDate string
Mandatory
The expiry date for the card. Provide as MMYY.
nickname string
The name the Customer provides for their card to allow easy selection where they register multiple cards.
defaultCard boolean
Indicates if the card being used should become the Customer’s default card.
cardHolderName string
The name printed on the card.
issueNumber number
The issue number for the card.
startDate string
The start date for the card. Provide as MMYY.
}
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.
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.
}
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.
version integer
Possible Values: 1, 2
Major version of 3D Secure applied to this transaction.
protocolVersion string
Possible Values: 1.0.2, 2.1.0, 2.2.0
Full protocol version of 3D Secure applied to this transaction.
versionsAttempted[ { Versions of 3D Secure that were attempted for this transaction, in order of use. This can be used to determine when 3DSv2 could not be used, and why.

A version will only be included in this list if it was meaningfully attempted, which means that the transaction must have been eligible (e.g. type, channel, payment method etc.) and the merchant’s account must have been capable (e.g. the corresponding 3D Secure version was enabled on the MID, etc.)

This property may be populated even if no others in this section are, e.g. to indicate that the issuer didn’t support any version of 3D Secure.
version integer
Possible Values: 1, 2
Major version of 3D Secure that was attempted.
availability string
Possible Values: INSUFFICIENT_DATA, ISSUER_NO_V2, ISSUER_NO_V1, ISSUER_NO_3DS, ERROR, AVAILABLE
High-level indication of the actual availability of the given 3D Secure version and what happened during the attempt to use it.
} ]
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, ATTEMPTED, ENROLMENT_CHECK_FAILURE, INCOMPLETE, NOT_AVAILABLE, NOT_IMPLEMENTED
The overall 3DS result for the transaction.
xid string
The ID used during 3DSv1 processing.
threeDSServerTransId string
Pay360 3DSv2 transaction ID.
dsTransactionId string
Directory Server 3DSv2 transaction ID.
acsTransactionId string
Access Control Server (ACS) 3DSv2 transaction ID.
challengeRequest string
Possible Values: NO_PREFERENCE, NO_CHALLENGE_REQUESTED, CHALLENGE_REQUESTED, CHALLENGE_MANDATED
Indicates whether a challenge was ultimately requested or not; this reflects the final 3DSv2 request made by Pay360 after taking into account any merchant preference and card scheme rules.
frictionless boolean
Whether the cardholder was authenticated without a challenge (frictionless flow).
authenticationStatus string
Possible Values: AUTHENTICATED, ATTEMPTED, FAILED, ERROR
The status of 3DSv1 authentication check.
authenticationIndicator string
Possible Values: Y, A, N, U
The indicator of the 3DSv1 authentication status.
enrolmentIndicator string
Possible Values: Y, N, U
The indicator of the 3DSv1 enrolment status.
enrolmentDateTime string
The date and time the 3DSv1 enrolment check was performed in ISO-8601 format.
enrolmentStatus string
Possible Values: ENROLLED, NOT_ENROLLED, UNABLE_TO_AUTHENTICATE
The status of the 3DSv1 enrolment check.
}
customer { Information about the Customer.
id string
Our ID for the Customer.
merchantRef string
Your reference for the Customer.
}
financialServices { Supplementary data for Financial Services payments, echoed from the request
dateOfBirth string
Date of birth of the recipient
surname string
Surname/family name of the recipient
accountNumber string
Account number used to identify the recipient or loan
postCode string
First part of the recipient’s postal code
}
accountFunding { Supplementary data for Account Funding Transactions (AFT), echoed from the request
recipient { Details about the funding recipient
givenName string
Recipient’s given name
surname string
Recipient’s surname/family name
address string
Recipient’s address
city string
Recipient city
state string
Recipient state/province code
countryCode string
Recipient country code (ISO-3166-alpha-3)
}
}
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.
paymentClass string
The classification of payment method used. Eg. Card, Cash, PayPal
registered boolean
Indicates that the customer choose to register this card payment method. This field will not be present for non-card payment methods.
isPrimary boolean
Indicates if this was Customer’s primary registered payment method.
card { Use if you want to provide your Customer’s card details. This section is mandatory if you are not providing a token (merchant or CardLock) or details of the Customer’s default card.
issueNumber string
The issue number of the card used in the request.
cardToken string
The token for the card.
cardHolderName string
The Cardholder’s name.
issuer string
The Issuer of the card.
maskedPan string
The masked card number. eg. 123456******1234
cardFingerprint string
An identifier for the card number. If multiple customers register cards with the same PAN they will get different card tokens, but the card fingerprint will be the same for them all.
issuerCountry string
The country of the card Issuer.
expiryDate string
The expiry date of the card. Formatted as MMYY.
validDate string
The valid from date of the card. Formatted as MMYY.
cardType string
The type of card. Eg. MC_DEBIT, VISA_CREDIT, AMEX.
cardUsageType string
The usage type of card. Eg. DEBIT, CREDIT.
cardScheme string
The scheme of card. Eg. VISA, MASTERCARD, AMEX.
cardCategory string
The category of card. Eg. CREDIT, DEBIT, CORPORATE, BUSINESS.
cardNickname string
The name the Customer provided for their Card to allow easy selection where they registered multiple cards.
}
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
Payment session without customer (guest checkout)

POST /hosted/rest/sessions/{instId}/payments
{
    "transaction": {
        "money": {
            "currency": "GBP",
            "amount": {
                "fixed": "25.00"
            }
        },
        "merchantReference": "TXN-0001",
        "description": "Sample Payment"
    },
    "session": {
        "returnUrl": {
            "url": "https://www.example.com"
        }
    }
}

HTTP/1.1 201 Created
{
    "sessionId": "SMjq3XseLouVCMLaZMpiGfKjf",
    "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjq3XseLouVCMLaZMpiGfKjf/begin/SMjq3XseLouVCMLaZMpiGfKjf",
    "status": "SUCCESS"
}
Payment session for a new customer

POST /hosted/rest/sessions/{instId}/payments
{
    "transaction": {
        "money": {
            "currency": "GBP",
            "amount": {
                "fixed": "25.00"
            }
        },
        "merchantReference": "TXN-0002",
        "description": "Sample Payment"
    },
    "customer": {
        "identity": {
            "merchantCustomerId": "CUST-0001"
        },
        "details": {
            "name": "John Smith",
            "emailAddress": "john.smith@example.com",
            "telephone": "+441234567890"
        }
    },
    "session": {
        "returnUrl": {
            "url": "https://www.example.com"
        }
    }
}

HTTP/1.1 201 Created
{
    "sessionId": "SMjrlEyyTsNRDm5JxhhnZJvk-",
    "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjrlEyyTsNRDm5JxhhnZJvk-/begin/SMjrlEyyTsNRDm5JxhhnZJvk-",
    "status": "SUCCESS"
}
Payment session for an existing customer

POST /hosted/rest/sessions/{instId}/payments
{
    "transaction": {
        "money": {
            "currency": "GBP",
            "amount": {
                "fixed": "25.00"
            }
        },
        "merchantReference": "TXN-0003",
        "description": "Sample Payment"
    },
    "customer": {
        "identity": {
            "merchantCustomerId": "CUST-0001"
        }
    },
    "session": {
        "returnUrl": {
            "url": "https://www.example.com"
        }
    }
}

HTTP/1.1 201 Created
{
    "sessionId": "SMjpEpId4uPpLAofG9VbrrJ1g",
    "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjpEpId4uPpLAofG9VbrrJ1g/begin/SMjpEpId4uPpLAofG9VbrrJ1g",
    "status": "SUCCESS"
}
Payment session offering various amount options and custom input

POST /hosted/rest/sessions/{instId}/payments
{
    "transaction": {
        "money": {
            "currency": "GBP",
            "amount": {
                "suggested": {
                    "choice": {
                        "option": [
                            "10.00",
                            "20.00",
                            "50.00"
                        ]
                    },
                    "range": {
                        "min": "1.00",
                        "max": "150.00"
                    }
                }
            }
        },
        "merchantReference": "TXN-0004",
        "description": "Sample Payment"
    },
    "session": {
        "returnUrl": {
            "url": "https://www.example.com"
        }
    }
}

HTTP/1.1 201 Created
{
    "sessionId": "SMjov7cJjehNBOqo3_PwDqx0R",
    "redirectUrl": "https://secure.mite.pay360.com/hosted/SMjov7cJjehNBOqo3_PwDqx0R/begin/SMjov7cJjehNBOqo3_PwDqx0R",
    "status": "SUCCESS"
}
Hosted endpoint
endpoint: /hosted/rest/sessions/{instId}/payments
method: POST
summary: process Payment

parameters:

Name
Data Type
Description
instId
string
The installation id
request body:
{
transaction { Mandatory
Details of the transaction you want to create.
merchantReference string
Your reference for the transaction.
money { Mandatory
currency string
Mandatory
The currency of your Customer’s transaction. Use the 3 character ISO-4217 code.
amount { Mandatory
Choose one of fixed, choice, range or suggested amount specifications.
fixed float
Choice
Use if you want your customer to only make a payment for a fixed amount. The customer can not change the amount.
choice { Choice
Use if you want your customer to select from a predefined set of amounts.
option [ array
Mandatory
Mandatory if Amount Choice included in the request.
item float
]
}
range { Choice
Use if you want your customer to choose an amount between a minimum and maximum value or within a part-bounded range. You can also provide a default amount. This can be overtyped by the customer if they want to.
min float
Mandatory if Amount Range included in the request and max value not present.
max float
Mandatory if Amount Range included in the request and min value not present.
default float
}
suggested { Choice
Use if you want to your customer to choose an amount between a minimum and maximum value or from a predefined set of amounts.
choice { Mandatory
Mandatory if Suggested included in the request.
option [ array
Mandatory
item float
]
}
range { Mandatory
Mandatory if Suggested included in the request.
min float
max float
default float
}
}
}
}
description string
The description of the transaction.
commerceType string
Possible Values: ECOM, MOTO, CNP
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. If no channel is provided we’ll automatically classify the channel as WEB
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 recurring Continuous Authority relationship from this transaction.
instalment boolean
Set this field if you want to start an instalment Continuous Authority relationship from this transaction.
continuousAuthorityAgreement { Conditional
The continuous authority agreement established with the cardholder. Required if you want to process a transaction initiating a recurring or instalment series using 3DSv2
minFrequency integer
Mandatory
Minimum number of days expected between payments in a recurring or instalment sequence. Must be >= 1.
expiry string
Mandatory
Date (YYYY-MM-DD) at which recurring/instalment agreement expires, or at which it will need to be re-authenticated in order to continue. Must be in the future.
numberOfInstalments integer
Conditional
Total number of payments in an instalment sequence – including this one, if starting with a payment. Required only for instalments; must be >= 2.
}
do3DSecure boolean
Indicates if the transaction should be processed with 3DS. This will override account configuration for 3DS.
}
customer {
create boolean
Deprecated. Use ‘registered’ instead, as this will be removed in the future.
registered boolean
Indicates if you wish to create or use a registered customer. False if you do not wish to register your customer, otherwise set to true. Default value is true.
identity { Conditional
Mandatory when registering a new customer, or using an already registered customer, optional otherwise.
platformCustomerId string
Choice
Our ID for your customer.
merchantCustomerId string
Choice
Your ID for the customer.
}
details { Conditional
Mandatory when registering a new customer, optional otherwise. NB – If details element is present when fetching an existing customer, the details stored for that customer will be updated with those present in the request.
name string
Conditional
The Customer’s name
Mandatory when registering a new customer, optional otherwise.
address { Conditional
Mandatory when registering a new customer, optional otherwise. This is used to pre-populate the customers billing address fields.
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.
}
telephone string
Telephone number for the customer. For best results, use international format, e.g. “+441234567890”.
emailAddress string
Email address for the Customer.
ipAddress string
The Customer’s IP address.
}
}
financialServices {

Supplementary data for Financial Services payments, including loan repayments and other credit-related activities.

UK- and Europe-based merchants with merchant category code (MCC) 6012, and some merchants coded MCC 6051 or MCC 7299, are required to provide this information about the primary recipient, who may be different from the customer making payment. Consult your acquirer if you are not sure whether you should submit this.

Cannot be submitted in conjunction with accountFunding.
dateOfBirth string
Date of birth of the recipient, in YYYYMMDD format. For example, for Jan 2nd, 1980, this would be “19800102”.
surname string
Surname/family name of the 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
Account number used to identify the recipient 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
First part of the recipient’s postal code; up to six characters. For example, if the postal code is “LE11 3QF”, this would be “LE11”.
}
accountFunding {

Supplementary data for Account Funding Transactions (AFT), e.g. money transfers. You should provide this if advised by your acquirer.

Cannot be submitted in conjunction with financialServices.
recipient { Details about the funding recipient
givenName string
Recipient’s given name
surname string
Recipient’s surname/family name
address string
Recipient’s address (house/building name and number, street/road name, etc.)
city string
Recipient city
state string
Only for recipients based in the US or Canada
Recipient state/province code (2-3 characters), e.g. “CA”, “DE”, “MD”, “TN” et al. in the US; “AB”, “ON”, “QC”, “SK” et al. in Canada
countryCode string
Recipient country code (ISO-3166-alpha-3), e.g. “CAN”, “GBR”, “USA” et al.
}
}
locale string
The ISO-639-1 code for your Customer’s locale.
session { Mandatory
preAuthCallback { Details of the callback made before the transaction is sent for authorisation.
url string
Mandatory
The URL you want the callback or notification to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback or notification will be sent.
format string
Possible Values: REST_XML, REST_JSON
The format of the callback content.
}
postAuthCallback { Details of the callback made after the transaction is sent for authorisation.
url string
Mandatory
The URL you want the callback or notification to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback or notification will be sent.
format string
Possible Values: REST_XML, REST_JSON
The format of the callback content.
}
transactionNotification { Details of the notification sent after transaction completion.
url string
Mandatory
The URL you want the callback or notification to be sent to. This will override any defaults set on your account. Where a default is set and a blank URL field is specified, no callback or notification will be sent.
format string
Possible Values: REST_XML, REST_JSON
The format of the callback content.
}
returnUrl { Mandatory
The URL that we will return your customer to after processing the transaction.
url string
Mandatory
}
cancelUrl { The URL that we will return your customer to if they cancel the hosted session. If omitted the returnUrl is used if they cancel.
url string
Mandatory
}
restoreUrl { The URL of Pay360 hosted session. We’ll take your customer to this URL in the event they cancel their PayPal payment with the “Cancel and return to….” link. You will need to use this field if you iFrame our hosted product.
url string
Mandatory
}
skin The ID of the skin used to drive look and feel for this session. Refer to Customise hosted look and feel for more information.
}
customerNotice { Additional information/instructional text to display to the customer while collecting payment details; see Customer Notice
content string
Text to display to the cardholder, up to 1000 characters. Supports a limited subset of HTML.
locator string
Possible Values: FORM_TOP, FORM_AFTER, FORM_BOTTOM
Position of the notice on the page. Defaults to FORM_TOP if not set.
}
features { Holder of features that can be enabled/disabled during a hosted session.
paymentMethodRegistration string
Possible Values: always, optional
Allow the customer to choose if they wish their payment method to be registered.
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.
paymentMethods array
Possible Values in the Array: card, applepay, googlepay, paypal, openbanking, visacheckout
Specify which payment methods are to be displayed, in the specified order. The array should contain strings for the names of payment methods. This is only available for a version 2 skin. Any payment methods not enabled on your account will not be displayed.
newAccountPayoutEnabled boolean
If true, the customer requesting the payout will be able to complete it by entering a new payment account; the usual restriction of forcing payouts to go to an existing saved account won’t apply to this session. NOTE: This feature needs to be enabled on your processing account first; please contact our Implementations team if you wish to use this.
addNewPaymentMethodLink boolean
Works in conjunction with the newAccountPayoutEnabled flag. If true, the customer will always be able to enter a new payment account for the payout. If false, then the customer will be forced to use a saved account if they have one, but will still be able to enter a new payment account if they have none saved.
showResultsPage boolean
If true, after processing the transaction the user will be shown a page with the result, including key details of the transaction, including amount, transaction id, merchant reference, etc. Default is false, meaning it is up to the merchant to inform the customer of the result of the transaction.
NOTE: This option is only available when using a version 2 hosted skin, see Skin Properties
}
}
response:
{
sessionId string
Our ID for the hosted session.
redirectUrl string
The URL you should direct your customer to to start the hosted session.
status string
Possible Values: SUCCESS, FAILED
Indicates the status of the session creation.
reasonCode string
Further information about the status of the session creation.
reasonMessage string
Further information about the status of the session creation. This is where we will provide detailed information about any errors.
}

The status of a hosted session can be retrieved while it is in use, and for a limited time (up to 1 hour) afterwards. This is the recommended way to find out the id of the transaction after the user has been returned to your site. If the session is complete, then the transaction status in the response is that at the time the hosted session was terminated. The latest, and full, details of the transaction can then be retrieved using retrieve a transaction.

Retrieve session examples
Transaction is currently being processed
GET /hosted/rest/sessions/{instId}/{sessionId}/status

HTTP/1.1 200
{
    "status": "SUCCESS",
    "hostedSessionStatus": {
        "sessionId": "SMjogn8RQWJBF0ooyl1MA7p4S",
        "context": "https://secure.mite.pay360.com/hosted",
        "sessionState": "STARTED",
        "transactionState": {
            "transactionState": "PROCESSING"
        }
    }
}
Session completed with successful transaction
GET /hosted/rest/sessions/{instId}/{sessionId}/status

HTTP/1.1 200
{
    "status": "SUCCESS",
    "hostedSessionStatus": {
        "sessionId": "SMjogn8RQWJBF0ooyl1MA7p4S",
        "context": "https://secure.mite.pay360.com/hosted",
        "sessionState": "TERMINATED",
        "transactionState": {
            "id": "11802480907",
            "transactionState": "SUCCESS"
        }
    }
}
Session not found or no-longer available
GET /hosted/rest/sessions/{instId}/{sessionId}/status

HTTP/1.1 404
{
    "status": "FAILED",
    "reasonCode": "exception.sessionState.noSession",
    "reasonMessage": "Session not found"
}
Retrieve session endpoint
endpoint: /hosted/rest/sessions/{instId}/{sessionId}/status
method: GET
summary: retrieve a hosted session

parameters:

Name
Data Type
Description
instId
string
The installation id
sessionId
string
The session id
response:
{
status string
outcome of session retrieval request, SUCCESS or FAILED.
reasonCode string
code of session retrieval error.
reasonMessage string
message describing session retrieval error.
hostedSessionStatus {
sessionId string
The id of the session.
context string
web context of the hosted session.
sessionState string
session status, possible values:

  • INITIALISED – session created but not yet visited in a browser
  • STARTED – session in use but transaction not yet submitted
  • SUSPENDED – session is suspended either for 3-D Secure or merchant suspension via pre-auth callback
  • TERMINATED – session finished, it cannot be used again
  • EXPIRED – session has expired after being abandoned, it cannot be used again

 
transactionState {
id string
id of the transaction produced by the session, could change if processing retry is available, such as after PayPal cancel.
transactionState string
status of the transactions, possible values:

  • NOT_SUBMITTED – transaction request has not yet been submitted by customer
  • PROCESSING – transaction is being processed
  • PENDING – transaction is suspended, typically for 3-D Secure
  • SUCCESS – transaction was successful
  • FAILED – transaction failed
  • EXPIRED – transaction was abandoned
  • CANCELLED – transaction was cancelled
  • VOIDED – transaction was voided or reversed

 
}
}
}

Related topics