[go: nahoru, domu]
Payouts
Developer Documents‣Cards‣Payouts

The Payout request allows credits to be made to a Customer’s payment method without referencing an original transaction.  This is typically used by Gaming merchants who need to give their customers their winnings.  A Payout processes Payouts via Visa cards as a CFT (Cardholder Funds Transfer) and MasterCard cards as a PoW (Payment of Winnings).

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

Deferred Payouts
If a Payout transaction is deferred then it will use a dual transaction model that consists of an initial transaction of type PAYOUT_INITIALIZE and a secondary transaction of type PAYOUT_COMPLETE. The PAYOUT_INITIALIZE transaction will perform no authorisation but will create an initial transaction with all of the required details. The transaction can then be completed at a later point which will perform authorisation using the details supplied in the PAYOUT_INITIALIZE request and will result in a secondary PAYOUT_COMPLETE transaction.

A PAYOUT_INITIALIZE transaction can be completed by the following secondary transaction types PAYOUT_COMPLETE or PAYOUT_VOID.

Optimize Deferred Payouts
A payout transaction can be converted to a PAYOUT_INITIALIZE if Optimize is enabled and a rule is activated  with a defer outcome. Once Optimize has marked the transaction as defer the transaction will be converted to  PAYOUT_INITIALIZE and the transaction will be sent to a Queue for further investigation by a fraud analyst. Once the investigation is complete the fraud analyst will either reject or accept the transaction which would result in a secondary transaction of PAYOUT_VOID or PAYOUT_COMPLETE  respectively. Within Optimize the transaction could automatically expire if no action is taken and this could result in a PAYOUT_VOID transaction with a terminal state of EXPIRED.

APIHosted
API examples
Payout for existing customer with default card


POST /acceptor/rest/transactions/{instId}/payout
{
  "transaction": {
    "currency": "GBP",
    "amount": "1000.0",
    "description": "Sample Transaction",
    "merchantRef": "mer_txn_1234557",
    "commerceType": "MOTO",
    "channel": "MOTO"
  },
  "paymentMethod": {
    "fromCustomer": {
      "cv2": "111"
    }
  },
  "customer": {
    "merchantRef": "mer_cust_131241413"
  },
  "recipient" : {
    "givenName" : "John",
    "surname" : "Smith"
  }
}

HTTP/1.1 201
{
  "processing": {
    "authResponse": {
      "statusCode": "00",
      "message": "ACQUIRER OK",
      "authCode": "100000",
      "gatewayReference": "1380124540635520-PASS",
      "gatewaySettlement": "2014-10-29",
      "gatewayCode": "1",
      "gatewayMessage": "ACCEPTED",
      "avsAddressCheck": "NOT_PROVIDED",
      "avsPostcodeCheck": "NOT_PROVIDED",
      "cv2Check": "MATCHED",
      "status": "AUTHORISED"
    },
    "route": "MCPE"
  },
  "paymentMethod": {
    "card": {
      "cardToken": "hJzbc9ccR9CHLlita5g5Jg",
      "new": false,
      "cardType": "VISA_DEBIT",
      "cardUsageType": "DEBIT",
      "cardScheme": "VISA",
      "maskedPan": "444433******1111",
      "expiryDate": "0115",
      "issuer": "Lloyds",
      "issuerCountry": "GBR",
      "cardHolderName": "John Smith",
      "cardNickname": "John",
      "validDate": "1111"
    },
    "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"
  },
  "customFields": {
    "fieldState": [
      {
        "name": "measure_CV2_FAILURES",
        "value": "0",
        "transient": false
      },
      {
        "name": "measure_NO_DATA_MATCH",
        "value": "0",
        "transient": false
      },
      {
        "name": "measure_ADDRESS_MATCH_ONLY",
        "value": "0",
        "transient": false
      },
      {
        "name": "measure_TOTAL_CARD_SPEND",
        "value": "3000.00",
        "transient": false
      }
    ]
  },
  "threeDSecure": {},
  "customer": {
    "id": "10501",
    "merchantRef": "mer_cust_131241413"
  },
  "transaction": {
    "transactionId": "13503139522",
    "merchantRef": "mer_txn_1234557",
    "status": "SUCCESS",
    "type": "PAYOUT",
    "amount": 1000,
    "consumerSpend": 1000,
    "currency": "GBP",
    "transactionTime": "2014-01-06T17:34:02.602Z",
    "receivedTime": "2014-01-06T17:34:02.602Z",
    "channel": "WEB"
  },
  "outcome": {
    "status": "SUCCESS",
    "reasonCode": "S100",
    "reasonMessage": "Authorised"
  },
  "recipient": {
    "givenName": "John",
    "surname": "Smith"
  }
}
Deferred Payout for existing customer with default card


POST /acceptor/rest/transactions/{instId}/payout
{
  "transaction" : {
    "currency" : "GBP",
    "amount" : 1000.0,
    "description" : "Sample Transaction",
    "merchantRef" : "mer_txn_1234556",
    "commerceType" : "MOTO",
    "deferred" : true
  },
  "paymentMethod" : {
    "fromCustomer" : {
      "cv2" : "123"
    }
  },
  "customer" : {
    "id" : "10503"
  },
  "recipient" : {
    "givenName" : "John",
    "surname" : "Smith"
  }
}



HTTP/1.1 201
{
  "processing" : {
    "decision" : {
      "decisionResult" : "PROCEED",
      "decisionSource" : "RULE",
      "requestedType" : "PAYOUT_INITIALIZE",
      "decidedType" : "PAYOUT_INITIALIZE"
    }
  },
  "paymentMethod" : {
    "registered" : true,
    "card" : {
      "cardToken" : "MT_Jz-nzs70Tki6ac0r5ZkGeQ",
      "cardFingerprint" : "=cCoH9xYatDtG4YNAYCLOhItqRcU",
      "new" : false,
      "cardType" : "VISA_DEBIT",
      "cardUsageType" : "DEBIT",
      "cardScheme" : "VISA",
      "cardCategory" : "CREDIT",
      "maskedPan" : "100035******0007",
      "expiryDate" : "0620",
      "issuer" : "DATACASH",
      "issuerCountry" : "GBR",
      "cardHolderName" : "John Smith",
      "cardNickname" : "John",
      "validDate" : "1111"
    },
    "billingAddress" : {
      "line1" : "Flat 1 ",
      "line2" : "Cauldron house",
      "line3" : "A Street",
      "line4" : "",
      "city" : "Bath",
      "region" : "Somerset",
      "postcode" : "BA1 234",
      "country" : "United Kingdom",
      "countryCode" : "GBR"
    },
    "paymentClass" : "CARD"
  },
  "customFields" : {
    "fieldState" : [ ]
  },
  "customer" : {
    "id" : "10503",
    "merchantRef" : "mer_cust_131241412"
  },
  "transaction" : {
    "transactionId" : "10000000",
    "deferred" : true,
    "merchantRef" : "mer_txn_1234556",
    "merchantDescription" : "Sample Transaction",
    "status" : "SUCCESS",
    "stage" : "AUTHORISATION",
    "type" : "PAYOUT_INITIALIZE",
    "amount" : 1000.00,
    "consumerSpend": 0,
    "currency" : "GBP",
    "transactionTime" : "2019-06-19T16:08:53.483+01:00",
    "receivedTime" : "2019-06-19T16:08:53.483+01:00"
  },
  "outcome" : {
    "status" : "SUCCESS",
    "reasonCode" : "S100",
    "reasonMessage" : "Payout initialize successful"
  },
  "recipient": {
    "givenName": "John",
    "surname": "Smith"
  },
  "trace" : "Tl8ukebJwp9cI9sZye0yqNw",
  "link" : [ {
    "rel" : "transaction",
    "href" : "https://api.mite.pay360.com/acceptor/rest/transactions/111111/13043713446"
  } ]
}
API Endpoint
endpoint: /acceptor/rest/transactions/{instId}/payout
method: POST
summary: process Payout

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, CNP
The commerce type for your Customer’s transaction.
channel string
Mandatory
Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER
The sales channel for your Customer’s transaction.
merchantRef Your reference for the transaction. Max length: 255. It’s recommended that you keep this unique.
description The description of the transaction. Maximum length: 255.
deferred boolean
Indicates if the payout should have a dual transaction model of PAYOUT_INITIALIZE and PAYOUT_COMPLETE.
}
locale 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 { 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.
}
paymentMethod { Mandatory
fromCustomer { Mandatory
Use if you want to use your Customer’s default card.
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.
pan string
Mandatory
The card number.
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.
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.
}
}
recipient { Payout recipient details, required by some acquirers.
givenName string
Recipient given name.
surname string
Recipient surname.
}
}
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.
} Information about where to send your customer in the case of 3DS or a Callback.
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.
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,PAYOUT,PREAUTH,REFUND,CAPTURE,PREAUTH_VOID,PAYMENT_VOID,REPEAT,CASH_ISSUE,CASH_PAYMENT,CASH_EXPIRE,VERIFY,
PAYMENT_INITIALIZE,PAYMENT_UPDATE,PAYMENT_COMPLETE,PAYOUT_INITIALIZE,PAYOUT_COMPLETE,PAYOUT_VOID,PAYOUT_UPDATE
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, CNP
The Commerce Type for your Customer’s refund.
channel string
Possible Values: WEB, MOBILE, SMS, RETAIL, MOTO, IVR, OTHER
The Sales Channel for your Customer’s refund. If not provided the it will be inherited from the original transaction
}
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.
}
}
customer { Information about the Customer.
id string
Our ID for the Customer.
merchantRef string
Your reference for the Customer.
}
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.
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 {
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
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.
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.
}
}
recipient { Payout recipient details, required by some acquirers.
givenName string
Recipient given name.
surname string
Recipient surname.
}
}
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"
    }
  },
  "recipient" : {
    "givenName" : "John",
    "surname" : "Smith"
  }
}

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

parameters:

Name
Data Type
Description
instId
string
The installation id
request body:
{
transaction { Mandatory
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
}
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
option [ array
Mandatory
item float
]
}
range { Mandatory
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.
}
customer { Mandatory
identity { Mandatory
Specify an existing customer with the platformCustomerId, or specify a new or existing customer with the merchantCustomerId.
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 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.
}
recipient { Payout recipient details, required by some acquirers.
givenName string
Recipient given name.
surname string
Recipient surname.
}
}
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.
}