Create a payout

Definition: POST /v1/payouts

To initiate a payout, you must create a payout object. The parameters of the payout are sent in the message body as a JSON object. There are two ways in which a payout can be initiated:

  • First one is when you create a payout object with all the necessary card details, like in the below example.

    Request:

    POST https://securetest.smart2pay.com/v1/payouts
Authorization: Basic MTAxMDpnYWJp

{
 "Payout": {
   "MerchantTransactionID": "test_h4",
   "Amount": 1000,
   "Currency": "EUR",
   "Description": "payment product",
   "Card": {
     "HolderName": "John Doe",
     "Number": "4548812049400004",
     "ExpirationMonth": "02",
     "ExpirationYear": "2029"
    }
  }
}

    Response:

    HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "Payout": {
    "ID": 214,
    "SiteID": 1010,
    "Created": "20181016133234",
    "MerchantTransactionID": "test_h4",
    "OriginatorTransactionID": null,
    "Amount": "1000",
    "Currency": "EUR",
    "Description": "payment product",
    "StatementDescriptor": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
    }
  }
}

  • The second one is when you create a payout object containing only the Credit Card Token that was received in a previous card payment.

    If you initiate a Card payment and you set the GenerateCreditCardToken parameter to true, a token element is sent in the response, containing the value of the newly created credit card token.

    The token received in the response can be used to initiate future payouts.

    Request:

    POST https://securetest.smart2pay.com/v1/payouts
Authorization: Basic MTAxMDpnYWJp

{
  "Payout": {
    "MerchantTransactionID": "s2ptest_i11",
    "Amount": "100",
    "Currency": "EUR",
    "Description": "Payout Token Test",    
    "CreditCardToken": {
      "Value": "C0D510746B513D66093609AA92BDA295"
    }
  }
}

    Response:

    HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "Payout": {
    "ID": 219,
    "SiteID": 1010,
    "Created": "20190612130707",
    "MerchantTransactionID": "s2ptest_i11",
    "OriginatorTransactionID": null,
    "Amount": "100",
    "Currency": "EUR",
    "Description": "Payout Token Test",
    "StatementDescriptor": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
    }
  }
}

In case of an API error, an HTTP 4xx (you did something wrong) or HTTP 5xx (we did something wrong) response is returned.

For more information about the reasons of a wrong request response see our section Card Processing Return Codes.

Request:

POST https://securetest.smart2pay.com/v1/payouts
Authorization: Basic MTAxMDpnYWJp

{
  "Payout": {
    "MerchantTransactionID": "test_h5",
    "Amount": 1000,
    "Currency": "EUR",
    "Description": "payment product"
  }
}

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "Payout": {
    "InvalidRequestID": "i3355",
    "ID": null,
    "SiteID": 1010,
    "Created": null,
    "MerchantTransactionID": "test_h5",
    "OriginatorTransactionID": null,
    "Amount": "1000",
    "Currency": "EUR",
    "Description": "payment product",
    "StatementDescriptor": null,
    "Status": {
      "ID": null,
      "Info": null,
      "Reasons": [
      {
        "Code": 1206,
        "Info": "CardDetails are missing"
        }
      ]
    }
  }
}

Card Payout Notification

We will notify you about the new status of the payout to the Notification URL you setup in the Merchant Dashboard. The format of the received notification has the same structure as the response of the initial request.

You need to respond with HTTP code 204 (No Content)!

Payout notification format:

Authorization: Basic MTAxMDpnYWJp

{
  "Payout": {
    "ID": 214,
    "SiteID": 1010,
    "Created": "20181016133234",
    "MerchantTransactionID": "test_h4",
    "OriginatorTransactionID": null,
    "Amount": "1000",
    "Currency": "EUR",
    "Description": "payment product",
    "StatementDescriptor": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
    }
  }
}

Response:

204 No Content

Get information on a specific payout

You can get information about a payout by using GET HTTP request.

Definition: GET /v1/payouts/{id}

Where:
  • {id} – GlobalPay Payout ID

Request:

GET https://securetest.smart2pay.com/v1/payouts/214
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Payout": {
    "ID": 214,
    "SiteID": 1010,
    "Created": "20181016133234",
    "MerchantTransactionID": "test_h4",
    "OriginatorTransactionID": null,
    "Amount": "1000",
    "Currency": "EUR",
    "Description": "payment product",
    "StatementDescriptor": null,
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
    }
  }
}

Get the status of a payout

You can get the status of a payout by using the following GET HTTP request.

Please note that this method sends only the status information about a payout. To receive more information about a payout please go to our section Get information on a specific payout.

Definition: GET /v1/payouts/{id}/status

Where:
  • {id} – GlobalPay Payout ID

Request:

GET https://securetest.smart2pay.com/v1/payouts/214/status
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Payout": {
    "ID": 214,
    "MerchantTransactionID": "test_h4",
    "Status": {
      "ID": 2,
      "Info": "Success",
      "Reasons": []
    }
  }
}

Get a list of payouts

Without specifying any parameters a list of payouts is returned. Please be aware that only a limited amount of details for each payout will be provided.

Definition: GET /v1/payouts

Request:

GET https://securetest.smart2pay.com/v1/payouts
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Payouts": [
        {
            "ID": 214,
            "SiteID": 1010,
            "Created": "20181016133234",
            "MerchantTransactionID": "test_h4",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": null,
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        },
        {
            "ID": 213,
            "SiteID": 1010,
            "Created": "20181016133041",
            "MerchantTransactionID": "Laur-1539696641",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        },
        {
            "ID": 212,
            "SiteID": 1010,
            "Created": "20181016133024",
            "MerchantTransactionID": "Laur-1539696624",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 4,
                "Info": "Failed",
                "Reasons": [
                    {
                        "Code": 5065,
                        "Info": "Card not found within table of ranges."
                    }
                ]
            }
        },
        {
            "ID": 211,
            "SiteID": 1010,
            "Created": "20181016132837",
            "MerchantTransactionID": "Laur-1539696517",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 1,
                "Info": "Open",
                "Reasons": []
            }
        },
        {
            "ID": 210,
            "SiteID": 1010,
            "Created": "20181016123606",
            "MerchantTransactionID": "Laur-1539693367",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 1,
                "Info": "Open",
                "Reasons": []
            }
        },
        {
            "ID": 209,
            "SiteID": 1010,
            "Created": "20181016123450",
            "MerchantTransactionID": "Laur-1539693291",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 1,
                "Info": "Open",
                "Reasons": []
            }
        }
    ]
}

Get a list of payouts (filtered)

You can specify various filters as parameters in the query string in order to get a customized list of payouts.

Requests:

GET https://securetest.smart2pay.com/v1/payouts?limit=3
Authorization: Basic MTAxMDpnYWJp
GET https://securetest.smart2pay.com/v1/payouts?maximumAmount=1000
Authorization: Basic MTAxMDpnYWJp

The following table describes the possible filters you can use. You can mix the filters so you can obtain the desired results.

FILTERS
Field Description Data type
limit The maximum number of items that will be returned Long
offset A list of payments starting with the value of the offset parameter will be returned. The offset parameter can also be used together with the limit parameter to select specific entries within a list of payments. String
startDate The date and time after which the payments are returned DateTime

(YYYYMMDDHHMMSS)
endDate The date and time until which the payments are returned DateTime

(YYYYMMDDHHMMSS)
country Only the transactions having this country code will be returned String

(ISO 3166-1-alpha-2)
currency Only the transactions having this currency code will be returned String

(ISO 4217)
minimumAmount Only the payments with an amount higher than this will be returned Integer (last 2 digits representing the decimal part)
maximumAmount Only the payments with an amount lower than this will be returned Integer (last 2 digits representing the decimal part)
merchantTransactionID Only the payment having this merchantTransactionID will be returned String

^[0-9a-zA-Z_-]{1,50}$
statusID Only the transactions having this statusID will be returned. Integer

The ID of the payment status can have the following values: 1 – Open, 2 – Success, 3 – Cancelled, 4 – Failed, 5 – Expired, 9 – Authorized.
methodTransactionID Only the payments having this methodTransactionID will be returned. This transaction ID from the payment method provider can be used for customer support. String

^[0-9a-zA-Z_-]{1,50}$

Here is an example of a request with the limit filter set to 3. This means that it will only return 3 transactions in a descending order.

Request:

GET https://securetest.smart2pay.com/v1/payouts?limit=3
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Payouts": [
        {
            "ID": 214,
            "SiteID": 1010,
            "Created": "20181016133234",
            "MerchantTransactionID": "test_h4",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": null,
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        },
        {
            "ID": 213,
            "SiteID": 1010,
            "Created": "20181016133041",
            "MerchantTransactionID": "Laur-1539696641",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        },
        {
            "ID": 212,
            "SiteID": 1010,
            "Created": "20181016133024",
            "MerchantTransactionID": "Laur-1539696624",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 4,
                "Info": "Failed",
                "Reasons": [
                    {
                        "Code": 5065,
                        "Info": "Card not found within table of ranges."
                    }
                ]
            }
        }
    ]
}

You can also mix various filters to get specific results. Here is an example of a request with the limit filter set to 2 and the currency EUR. This means that it will return the last two payout entries that have the transaction currency EUR.

Request:

GET https://securetest.smart2pay.com/v1/payouts?limit=2&currency=EUR
Authorization: Basic MTAxMDpnYWJp

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "Payouts": [
        {
            "ID": 214,
            "SiteID": 1010,
            "Created": "20181016133234",
            "MerchantTransactionID": "test_h4",
            "OriginatorTransactionID": null,
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": null,
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        },
        {
            "ID": 213,
            "SiteID": 1010,
            "Created": "20181016133041",
            "MerchantTransactionID": "Laur-1539696641",
            "OriginatorTransactionID": "test123456789!$%#",
            "Amount": "1000",
            "Currency": "EUR",
            "Description": "payment product",
            "StatementDescriptor": "card payment",
            "BillingAddress": {
                "ID": 9622,
                "City": "Iasi",
                "ZipCode": "700049",
                "State": "Iasi",
                "Street": "Sf Lazar",
                "StreetNumber": "371",
                "HouseNumber": "---",
                "HouseExtension": "---",
                "Country": "RO"
            },
            "Status": {
                "ID": 2,
                "Info": "Success",
                "Reasons": []
            }
        }
    ]
}