[go: nahoru, domu]
Payments by API
Developer Documents‣PayPal‣Payments by API

Use the following request to submit a PayPal payment that authorises and settles funds in a single step.

If you are using Cashier API, you will need to pass your customer to PayPal so they can logon. When you do that we suspend the transaction at Pay360. Once your customer has finished making their Payment at PayPal you will need to resume the transaction with us so we can complete our processing.

If you are using our Hosted Cashier, we will handle the customer redirect to PayPal for you. In order to achieve the best customer experience you may need to send us additional information depending on whether you redirect or iFrame the Hosted Cashier.

Both products allow the customer to return to the checkout (ours if you are using Hosted Cashier, yours if you are using the Cashier API) if they decide to Cancel the payment at PayPal.

APIHosted
API examples
Payment with PayPal

POST /acceptor/rest/transactions/{instId}/payment
{
  "transaction": {
    "currency": "GBP",
    "amount": 1000,
    "description": "Sample Transaction",
    "merchantRef": "mer_txn_1234556",
    "commerceType": "MOTO",
    "channel": "WEB"
  },
  "paymentMethod": {
    "paypal": {
      "returnUrl": "http://merchant-returnUrl.com",
      "cancelUrl": "http://merchant-cancelUrl.com"
    }
  },
  "customer": {
    "merchantRef": "mer_cust_131241412",
    "displayName": "Mr O Whatasillyname",
    "billingAddress": {
      "line1": "Flat 1 ",
      "line2": "Cauldron house",
      "line3": "A Street",
      "line4": "Twertonia",
      "city": "Bath",
      "region": "Somerset",
      "postcode": "BA1 234",
      "countryCode": "GBR"
    },
    "email": "test@test.com",
    "telephone": "0123 456 789",
    "defaultCurrency": "GBP",
    "ip": "212.58.253.67"
  }
}

Response
{
  "clientRedirect": {
    "type": "REDIRECT",
    "url": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-19N35258J27922454&useraction=commit",
    "frame": "TOP"
  },
  "paymentMethod": {
    "paymentClass": "PAYPAL"
  },
  "customer": {
    "merchantRef": "mer_cust_131241412"
  },
  "transaction": {
    "transactionId": "13625805484",
    "merchantRef": "mer_txn_1234556",
    "status": "PENDING",
    "type": "PAYMENT",
    "amount": 1000,
    "consumerSpend": 0,
    "currency": "GBP",
    "transactionTime": "2014-08-06T00:22:38.739+01:00",
    "receivedTime": "2014-08-06T00:22:38.739+01:00",
    "channel": "WEB"
  },
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "U103",
    "reasonMessage": "Suspended by PayPal"
  },
  "link": [
    {
      "rel": "transaction",
      "href": "https://api.mite.pay360.com/acceptor/rest/transactions/9999/13625805484"
    }
  ]
}
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.
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.
description string
The description of the transaction. Maximum length: 255.
}
locale string
The ISO-639 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 {
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.
}
paymentMethod { Mandatory
paypal { Mandatory
Include if the payment is being made with PayPal.
returnUrl string
The location where the Customer will be redirected after he finishes the PayPal session.
cancelUrl string
The location where the Customer will be redirected if the cancels the PayPal session.
accessToken string
The PayPal access token to be used in the PayPal session for “seamless checkout”. If not provided or not valid at the time of use, the customer will be redirected to the PayPal login.
}
}
}
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.
type string
url string
The URL the Customer should be redirected to.
}
transaction {
transactionId string
Our ID for the transaction.
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 the PayPal redirect response 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.
channel string
Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER
The Sales Channel of the transaction.
}
customer { Information about the Customer.
id string
Our ID for the Customer.
merchantRef string
Your reference for the Customer.
}
outcome { Information about the overall 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.
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
}
}
Hosted examples
Hosted Session Initialisation

POST /hosted/rest/sessions/{instId}/payments
{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/transactionResult?MERCHANTREF=931143931143"
    }
  },
  "transaction": {
    "merchantReference": "931143931143",
    "money": {
      "currency": "GBP",
      "amount": {}
    },
    "description": "HFTransactionDescriptionFor-931143931143"
  },
  "customer": {
    "create": true,
    "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"
    }
  },
  "customFields": {}
}

Hosted Session Initialisation Response
{
  "sessionId": "c904e5dc-c84e-4727-9364-8445af570218",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/97c79839-75cb-4b9e-a1a6-35e79bef7e78/begin/c904e5dc-c84e-4727-9364-8445af570218",
  "status": "SUCCESS"
}
Hosted Session Initialisation - iFramed

POST /hosted/rest/sessions/{instId}/payments
{
  "session": {
    "returnUrl": {
      "url": "https://www.example.com/transactionResult?MERCHANTREF=572117572117"
    },
    "restoreUrl": {
      "url": "https://www.example.com/restore"
    }
  },
  "transaction": {
    "merchantReference": "572117572117",
    "money": {
      "currency": "GBP",
      "amount": {}
    },
    "description": "HFTransactionDescriptionFor-572117572117"
  },
  "customer": {
    "create": true,
    "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"
    }
  },
  "customFields": {}
}

Hosted Session Initialisation Response
{
  "sessionId": "c904e5dc-c84e-4727-9364-8445af570218",
  "redirectUrl": "https://secure.mite.pay360.com/hosted/97c79839-75cb-4b9e-a1a6-35e79bef7e78/begin/c904e5dc-c84e-4727-9364-8445af570218",
  "status": "SUCCESS"
}
Hosted endpoint
endpoint: /acceptor/rest/transactions/{instId}/payment
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
item float
]
}
range { Choice
Use if you want your customer to choose an amount between a minimum and maximum value. You can also provide a default amount. This can be overtyped by the customer if they want to.
min float
max float
default float
}
}
}
}
description string
The description of the 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.
}
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.
name string
Conditional
The Customer’s name. Required when registering a new customer, optional otherwise.
address { The address of the Customer. 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 billing address country.
}
telephone string
Telephone number for the Customer.
emailAddress string
Email address for the Customer.
ipAddress string
The Customer’s IP address.
}
}
locale string
The ISO-639 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 the 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 string
The ID of the skin used to drive look and feel for this session. Refer to Customise hosted look and feel for more information.
}
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.
payPalAccessToken string
The PayPal access token to be used in the PayPal session for “seamless checkout”. If not provided or not valid at the time of use, the customer will be redirected to the PayPal login.
}
}
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.
}