NAV
curl

Authentication

Example of function to generate a signature in PHP:

<?php

function generate(array $parameters)
{
    sort($parameters, SORT_STRING);

    return hash_hmac('sha256', join('|', $parameters), 'PRIVATE_KEY');
}

Request and callback parameters are signed to make sure the values won’t be changed.

Rules to generate a signature:

  1. Sort parameter values ascending by value (case sensitive);
  2. Concatenate parameter values with a pipe (e.g. n3rf34j96j8rge4|123|example@example.com);
  3. Hash it with a HMAC­SHA256 algorithm.

Errors

Error Example

{
    "error": {
        "code": 40401,
        "message": "Project's public key is missing."
    }
}
Code Message
40001
400 Bad Request
 Project’s public key is missing.
40002
400 Bad Request
 User’s identifier is missing.
40003
400 Bad Request
 The credit card number is missing.
40004
400 Bad Request
 The credit card number is invalid.
40005
400 Bad Request
 The expiry is invalid.
40006
400 Bad Request
 The credit card security code is missing.
40007
400 Bad Request
 The credit card security code is invalid.
40008
400 Bad Request
 Credit card token is missing.
40009
400 Bad Request
 Credit card data is missing.
40010
400 Bad Request
 User’s email is missing.
40011
400 Bad Request
 User’s IP address is missing.
40012
400 Bad Request
 The credit card expiration month is missing.
40013
400 Bad Request
 The credit card expiration year is missing.
40014
400 Bad Request
 Missing merchant data.
40015
400 Bad Request
 The cardholder is invalid. Should contain no more than 21 characters.
40101
401 Unauthorized
 Signature is missing.
40102
401 Unauthorized
 Authentication token is missing.
40301
403 Forbidden
 Signature is invalid.
40302
403 Forbidden
 Authentication token is invalid.
40303
403 Forbidden
 Authentication token has expired.
40304
403 Forbidden
 Credit card token has expired.
40305
403 Forbidden
 Credit card token is already used.
40306
403 Forbidden
 Platform authentication token is invalid.
40307
403 Forbidden
 Platform authentication token is invalid.
40308
403 Forbidden
 User is blocked.
40309
403 Forbidden
 Credit card is blocked.
40310
403 Forbidden
 Recurring is disabled for requested user.
40311
403 Forbidden
 Recurring expired for requested user.
40312
403 Forbidden
 Card remembering is disabled for project.
40401
404 Not Found
 Project is missing.
40402
404 Not Found
 Credit card token is invalid.
40403
404 Not Found
 Transaction does not exist.
40404
404 Not Found
 Platform is missing.
40405
404 Not Found
 Reference recurrent transaction is missing.
40406
404 Not Found
 User is missing.
40407
404 Not Found
 Platform user is missing.
40501
405 Method Not Allowed
 Transaction is already completed.
40502
405 Method Not Allowed
 Recurring payments are too frequent for requested user.
40503
405 Method Not Allowed
 Unable to create recurrent transaction.
40504
405 Method Not Allowed
 Transaction cannot be reversed.
42201
422 Unprocessable Entity
 Not properly configured gateway.
50001
500 Internal Server Error
 Card tokenization error.

Callbacks

Example Request

curl CALLBACK_URL \
    -d signature=ea7379f5f09cef58e61afccf7eb73d6963ef286f96821cbfa8f2377076e5c59a \
    -d project=13 \
    -d user=47055 \
    -d id=1462905107214034164 \
    -d reference_id= \
    -d order_id= \
    -d amount=200 \
    -d price=1.99 \
    -d deposit=0 \
    -d earned=1.99 \
    -d vat_rate=18 \
    -d vat_amount=0.3035 \
    -d currency=USD \
    -d status=completed \
    -d sandbox=1 \
    -d attr_one=1 \
    -d attr_two="Hello world"

Callback URL can be set in project settings. You will receive the callback parameters via HTTP POST method. All parameters below are present in a request, but can be empty. When calculating a signature all parameter values must be treated as strings.

Parameter Description
project
integer(11)
 ID of your project.
user
string(128)
 ID of user.
id
string(19)
 ID of transaction.
reference_id
string(19)
 ID of a parent transaction. For example, in refund_completed callback it’ll be equal to an ID of transaction that is being refunded.
order_id
string(64)
 Your order ID, if it was provided.
amount
decimal(9,2) as string
 Amount of virtual currency to give to a user.
price
decimal(12,4) as string
 Price of transaction.
deposit
decimal(12,4) as string
 Amount of deposit taken from this transaction.
earned
decimal(12,4) as string
 Your revenue.
vat_rate
decimal(12,4) as string
 VAT rate in country of payment.
vat_amount
decimal(12,4) as string
 Calculated VAT amount. VAT is calculated from price, but is not subtracted from your earnings.
currency
string(3)
 Currency of transaction. Price, deposit and earned parameters are in this currency.
type
string(16)
 Type of callback. See the Callback types section.
status
string(16)
 Status of a transaction. See the Callback statuses section.
reason
string(255)
 May contain a reason for transaction.
sandbox
string(1)
 Represents your project’s state. Equals 1 if in sandbox, 0 otherwise.
attr_*
string
 Any custom attributes, that were used to create a payment. For example: attr_realm, attr_server, attr_landing.
signature
string(64)
 Make sure that the signature sent with the callback is correct. See the Authentication section.

Callback types

Type Description
transaction Fires if transaction status changes.

Callback statuses

Status Description
completed Transaction has completed successfully.
waiting_approval Transaction is waiting for approve.
processing Transaction is processing.
failed Transaction has failed.
verified Transaction is of type verification and has completed successfully. Funds in amount of 1 EUR were frozen and released to verify card.
refund_completed Transaction is reversed/refunded.
chargeback_completed Chargeback has completed because of a started dispute.
retrieval_completed Chargeback dispute is won. Funds taken with a chargeback are returned.
penalty_completed Penalty amount applied to transactions of type refund or chargeback.
payout_completed Payout is completed.
payout_failed Payout is failed.
payout_cancelled Payout is cancelled.
payout_abandoned Payout is abandoned.

Objects

Card-response object

Example object

{
    "lastFour": "1112",
    "mask": "************1112",
    "type": "visa",
    "scheme": "visa",
    "expirationMonth": 4,
    "expirationYear": 2020
}
Parameter Description
lastFour
string
 Last four digits of a card number.
mask
string
 Card number mask. Only last four digits are visible, others are hidden with asterisks.
type
string
 Card type (e.g. visa, mastercard). Deprecated: use scheme.
scheme
string
 Card scheme (e.g. visa, mastercard).
expirationMonth
integer
 Card expiration month.
expirationYear
integer
 Card expiration year.

Card object

Example object

Parameter Description
number
string
 PAN.
expiration_month
integer
 Expiration month.
expiration_year
integer
 Expiration year.
security_code
string
 CVV.
holder
string
 Cardholder.

ACS object

Example object

{
    "url": "https://bank.example.com/ACS/",
    "parameters": {
         "MD": "eyJ0cmFuc2Fj...",
         "PaReq": "eJxdUWF...",
         "TermUrl": "https://example.com/acs_return/"
    }
}
Parameter Description
url
string
 URL where user must be redirected using HTTP POST with each parameter from parameters object.
parameters
object
 Parameters (PaReq, MD, TermUrl) that must be passed to ACS. url ​as­is using the HTTP POST method.

Recurring object

Example object

{
     "frequency": 1,
     "endsAt": "2015­10­22T11:49:23+03:00"
}
Parameter Description
frequency
integer
 Minimal number of days between recurring payments.
endsAt
date in ISO 8601 format
 Last date when repeated payments will be available for a user.

Payout-type object

Example object

{
    "id": 1,
    "key": "SEPA",
    "label": "Sepa"
}
Parameter Description
id
integer
 Identifier of type.
key
string
 Key of type.
label
string
 Title of type.

Payout-parameter-control object

Example object

{
    "name": "description",
    "type": "text",
    "label": "Description",
    "required": false
}
Parameter Description
name
string
 Parameter name key.
type
string
 Data type of control.
label
string
 Title of control.
required
boolean
 Indicates whether parameter is required.

User object

Example object

{
    "id": 17,
    "identifier": "1",
    "displayName": "Username",
    "email": "test@example.com",
    "phone": "7777777777",
    "ip": "127.0.0.1",
    "locale": "ru"
}
Parameter Description
id
string
 User id.
identifier
string
 External user id.
displayName
string
 Username.
email
string
 User email.
phone
string
 User phone number.
ip
string
 User ip.
locale
string
 User locale.

Flow

Payment flow

  1. User inputs and submits card data;
  2. Merchant creates a temporary token for ​10 minutes​ via JSONP or AJAX;
  3. Merchant receives temporary token and other payment data on a server-side;
  4. Merchant charges a card;
  5. If payment ​status​ is ​authenticating​:
    1. Merchant POSTs ​acs.parameters​ to ​acs.url in a web browser;
    2. User inputs and submits his 3DSecure password;
    3. ACS. POSTs parameters (PaRes, MD) back to merchant’s ​acs_return_url​;
    4. Merchant authenticates a card;
    5. Merchant should check status of the payment;
  6. Merchant should check status of the payment;
  7. Status checking cases:
    • If ​status​ of payments is ​completed​ then merchant can provide a service to a user;
    • If ​status​ of payments is ​processing​ then merchant should recheck status of payment or wait for async callback;
  8. If ​remember​ was equal to 1, merchant will receive a ​permanentToken​ parameter when charging or authenticating a card. You can use ​permanent token without requiring a user to input card data again;
  9. If ​recurring​ was equal to 1, merchant will receive a recurring object, containing allowed recurring frequency and ending date. Merchant can make payments for a user using manual recurring;
  10. If ​verify_card​ was equal to 1, then transaction price will be set to 1 EUR, that will be put on hold and then instantly returned;
  11. verify_card​ can be effectively used with ​recurring, recurring_interval, recurring_trial​ or remember​ parameters as it checks the validity of a card via freezing and releasing funds on a card.
  12. Merchant receives asynchronous ​callback​ with payment details and can provide a service to a user if status is completed.

Payout flow

  1. Merchant collects common payout parameters;
    • For payout to a card:
      • a) Merchant creates a temporary token and passes it in cardToken parameter at step 3;
      • b) Merchant passes a card number at step 3 in account parameter;
    • For non-card payout like wallet, SEPA, etc. then merchant passes recipient account in account parameter at step 3;
  2. Merchant requests required parameters for payout;
  3. Merchant creates payout with collected parameters.

User

Resolve a user

Example Request

curl https://api2.paysend.com/v1/user/resolve \
    -d signature=135ef9ee89f1f1addc43211b70ff4d3a976ac44ff56b7470c178618f6f19c204 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d identifier=1 \
    -d display_name="Example User" \
    -d email="user@example.com" \
    -d phone=123456789 \
    -d locale=en \
    -d ip=127.0.0.1

Example Response:

{
    "id": 47055
}

Returns internal user ID. Creates a user if it doesn’t exist or returns an ID of existing user.

HTTP request

POST https://api2.paysend.com/v1/user/resolve

Request parameters

Parameter Description
project
required
 Public key of your project.
identifier
required
 Unique and unchangeable identifier of a user.
display_name
optional
 Full name of nickname of a user.
email
optional
 Email address of a user.
phone
optional
 Phone number of a user in international format, without the leading + and any separators.
locale
optional, default is project’s locale
 Locale of a user in ISO 639-1 format.
ip
required
 IP address of a user.
ua
optional
 User Agent string of a user. Max 255 symbols.
signature
required
 See the Authentication section.

Change recurring settings

Example Request

curl https://api2.paysend.com/v1/user/changeRecurring \
    -d signature=0da5b5a9165343d4de8073aaf91bc594e5fad7ef448202fdc688914168eaf658 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d user=47055 \
    -d interval=30 \
    -d price=3.50 \
    -d currency=USD

Example Response:

{
    "success": true
}

Changes recurring settings of a user.

HTTP request

POST https://api2.paysend.com/v1/user/changeRecurring

Request parameters

Parameter Description
project
required
 Public key of your project.
user
required
 ID of internal user. See the Resolve user section.
interval
optional
 Days between repeated payments. When set to 0, only manual recurring remains available.
price
optional
 Price of repeated payments.
currency
required if price is present
 Currency of repeated payments.
signature
required
 See the Authentication section.

Returns

Parameter Description
success
boolean
 Indicates whether change was successful.

Cancel recurring

Example Request

curl https://api2.paysend.com/v1/user/cancelRecurring \
    -d signature=814c669f58d48f91837591b59ca2f8ac3186c3d69081361bece6188299ba14a9 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d user=47055

Example Response:

{
    "success": true
}

Cancels repeated payments of a user.

HTTP request

POST https://api2.paysend.com/v1/user/cancelRecurring

Request parameters

Parameter Description
project
required
 Public key of your project.
user
required
 ID of internal user. See the Resolve user section.
signature
required
 See the Authentication section.

Returns

Parameter Description
success
boolean
 Indicates whether cancellation was successful.

Card

Create a token

Example Request

curl "https://api2.paysend.com/v1/card/getToken?\
    project=d55ad89070d6172cc0eeeecfdde2c554&\
    number=4012001037141112&\
    expiration_month=4&\
    expiration_year=2020&\
    security_code=123"

Example Response:

{
    "id": "11fe4b4d430eccc4ca59b8df31bc5d161b4d54020082362a7d389486f5349066",
    "expiresAt": "2015­05­22T11:21:37+03:00",
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "type": "visa",
        "expirationMonth": 4,
        "expirationYear": 2020
    }
}

Example response using JSONP callback:

myCallback({
    "id": "11fe4b4d430eccc4ca59b8df31bc5d161b4d54020082362a7d389486f5349066",
    "expiresAt": "2015­05­22T11:21:37+03:00",
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "type": "visa",
        "expirationMonth": 4,
        "expirationYear": 2020
    }
})

Stores card data into a vault and returns created temporary token ID. You can use token id to securely Charge a card.

HTTP request

GET https://api2.paysend.com/v1/card/getToken

Query parameters

Parameter Description
project
required
 Public key of your project.
number
required
 Card number without any separators.
expiration_month
required
 Integer representing the card’s expiration month.
expiration_year
required
 Four digit number representing card’s expiration year.
security_code
required
 Card security code (CVC, CVV2).
callback
optional
 Callback function name for JSONP.

Returns

Parameter Description
id
string
 Identifier of a token.
expiresAt
date in ISO 8601 format
 Date when token expires.
card
object
 Card object

Payment

Charge a card

Example Request

curl https://api2.paysend.com/v1/card/process \
    -d signature=129a12c0acb47b0b5c7a76f441070c5cfac495de40cc9520f0e9f07120f1b455 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d user=47055 \
    -d card_token=d5c83ed1575b6fa30e8b977016c75a5417c5c9d34930d7076e9e36f374577345 \
    -d price=5.99 \
    -d currency=USD \
    -d description="My custom description." \
    -d acs_return_url="https://example.com/acs_return/" \
    -d attr_product_id=123

Example of Complete Response

{
    "id": 1326123574311498453,
    "orderId": "1",
    "success": true,
    "referenceId": null,
    "price": "5.99",
    "fee": "0.0000",
    "currency": "USD",
    "type": "payment",
    "status": "completed",
    "createdAt": "2017-05-08T11:08:26+00:00",
    "updatedAt": "2017-05-08T11:08:34+00:00",
    "user": {
        "id": 17,
        "identifier": "1",
        "displayName": "User",
        "email": "user@example.com",
        "phone": "11111111111",
        "ip": "127.0.0.1",
        "locale": "ru"
    },
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "expirationMonth": 12,
        "expirationYear": 2034,
        "expiresAt": "2035-01-01T00:00:00+00:00",
        "holder": null,
        "scheme": "visa",
        "bankName": "EXTRAS TEST - VISA",
        "country": "US"
    },
    "acs": {
        "url": "https://bank.example.com/ACS/",
        "parameters": {
             "MD": "eyJ0cmFuc2Fj...",
             "PaReq": "eJxdUWF...",
             "TermUrl": "https://example.com/acs_return/"
        }
    },
    "permanentToken": "d5c83ed1575b6fa30e8b977016c75a5417c5c9d34930d7076e9e36f374577345",
    "recurring": {
         "frequency": 1,
         "endsAt": "2015­10­22T11:49:23+03:00"
    }
}

Charges a card for certain amount of currency.

HTTP request

POST https://api2.paysend.com/v1/card/process

Request parameters

Parameter Description
project
required
 Public key of your project.
user
required
 ID of internal user or User object. See the Resolve user section.
card_token
required if card is empty
 Token ID of a credit card. Can be ID of temporary or permanent token.
card
required if card_token is empty
 Card object you can use without generation of token.
price
required
 Integer or float number representing payment price.
currency
required
 Three letter currency code in ISO 4217 format.
order_id
optional
 Merchant’s order ID that will be returned back in a callback. string(64)
description
required
 Description of a payment.
3ds
optional, default is 0
 Allows to switch payment processing to 3D Secure mode. Only works if 3D Secure is not forced for particular project.
acs_return_url
optional
 URL where ACS will return user after the 3D Secure authentication. See Authenticate a card section for next steps.
remember
optional, default is 0
 Integer (1 or 0) that indicates whether user wants to remember his credit card in your service. If 1, then ​permanentToken​ in response will contain token ID, that is used to .
verify_card
optional, default is 0
 Use it to create a permanent token or setup repeated payments (recurring). If set to 1, then 1 EUR on user’s card will be frozen and released instantly.
recurring
optional, default is 0
 Indicates whether a user wants to subscribe to recurring payments.
recurring_interval
required if recurring is set to 1
 Days between repeated payments. When set to 0, only manual recurring remains available.
recurring_trial
optional, default is 0
 Trial period in days before starting repeated payments. First repeated payment will occur after trial period.
attr_*
optional
 Any custom attributes, that you want to be returned in a callback. For example: attr_realm, attr_server, attr_landing.
signature
required
 See the Authentication section.

Returns

Parameter Description
success
boolean
 Indicates whether payment was successful. If acs object is present indicates whether payment process can be continued.
id
bigint
 Identifier of a payment.
orderId
string
 Merchant’s order ID.
referenceId
bigint
 Reference transaction ID.
price
decimal
 Integer or float number representing payment price.
currency
string
 Three letter currency code in ISO 4217 format.
type
string
 Transaction type (payment, payout, exchange).
status
string
 Status of a current transaction.
fee
decimal
 Merchant’s fee.
card
object
 Card object
acs
object
 If this object is present, then card is enrolled for 3DSecure and it is required to redirect user to ACS.. See ACS object for details.
permanentToken
string, default is null
 ID of a permanent card token. Permanent card token is used to charge a card without requesting card data again. Although card data is not required, it’s still required to go through 3DSecure authentication.
recurring
object
 If this object is present, then user is enrolled to repeated payments. Repeated payments do not require 3DSecure authentication, unlike permanent tokens. See Recurring object for details.
createdAt
date(RFC3339)
 Transaction created at.
updatedAt
date(RFC3339)
 Transaction updated at.

Authenticate a card

Example of Complete Response

{
    "id": 1326123574311498453,
    "success": true,
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "type": "visa",
        "expirationMonth": 4,
        "expirationYear": 2020
    },
    "permanentToken": "9a083895d07ca58f6e5505bd19ed35ca9a083895d07ca58f6e5505bd19ed35ca",
    "recurring": {
         "frequency": 1,
         "endsAt": "2015­10­22T11:49:23+03:00"
    }
}

Authenticates a card using PaRes and MD parameters POST'ed back to acs_return_url from ACS.

HTTP request

POST https://api2.paysend.com/v1/card/authenticate

Request parameters

Parameter Description
project
required
 Public key of your project.
PaRes
required
 Payer authentication response.
MD
required
 Merchant data.
signature
required
 See the Authentication section.

Returns

Parameter Description
id
bigint
 Identifier of a payment.
success
boolean
 Indicates whether payment process can be continued.
card
object
 Card object
permanentToken
string, default is null
 ID of a permanent card token. Permanent card token is used to charge a card without requesting card data again. Although card data is not required, it’s still required to go through 3DSecure authentication.
recurring
object
 If this object is present, then user is enrolled to repeated payments. Repeated payments do not require 3DSecure authentication, unlike permanent tokens. See Recurring object for details.

Manual recurring

Example Request

curl https://api2.paysend.com/v1/card/processRecurring \
    -d signature=84d134b2d662777a7f9ac0256375582742c85f7de9b95ebda4c54826f78290e5 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d user=47055 \
    -d price=5.99 \
    -d currency=USD \
    -d order_id=12345 \
    -d description="My custom description."

Example Response

{
    "id": 1326123574311498453,
    "success": true,
    "orderId": "1",
    "referenceId": null,
    "price": "5.99",
    "fee": "0.0000",
    "currency": "USD",
    "type": "payment",
    "status": "completed",
    "createdAt": "2017-05-08T11:08:26+00:00",
    "updatedAt": "2017-05-08T11:08:34+00:00",
    "user": {
        "id": 17,
        "identifier": "1",
        "displayName": "User",
        "email": "user@example.com",
        "phone": "11111111111",
        "ip": "127.0.0.1",
        "locale": "ru"
    },
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "type": "visa",
        "expirationMonth": 4,
        "expirationYear": 2020
    }
}

Charges a user subscribed to repeated payments out of interval. Useful for automatic balance top up in certain services.

HTTP request

POST https://api2.paysend.com/v1/card/processRecurring

Request parameters

Parameter Description
project
required
 Public key of your project.
user
required
 ID of internal user. See the Resolve user section.
price
required
 Integer or float number representing payment price.
currency
required
 Three letter payment currency code in ISO 4217 format.
order_id
optional
 Merchant’s order ID that will be returned back in a callback. string(64)
description
optional
 Description of a payment.
signature
required
 See the Authentication section.

Returns

Parameter Description
id
bigint
 Identifier of a payment.
success
boolean
 Indicates whether request was successful.
orderId
string
 Merchant’s order ID.
referenceId
bigint
 Reference transaction ID.
price
decimal
 Integer or float number representing payment price.
currency
string
 Three letter currency code in ISO 4217 format.
type
string
 Transaction type (payment, payout, exchange).
status
string
 Status of a current transaction.
fee
decimal
 Merchant’s fee.
card
object
 Card object
user
User object
 User.

Reverse a payment

Example Request

curl https://api2.paysend.com/v1/transaction/reverse \
    -d signature=7f9a1409ee03da997dbd4bcc40066cd7ea58b12f41203471e67fcf477c9bca31 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d id=1226123574311498453 \
    -d amount=5.99 \
    -d comment="Suspected fraud."

Example Response

{
    "success": true,
    "id": 1326123574311498453,
    "orderId": "1",
    "referenceId": null,
    "price": "5.99",
    "fee": "0.0000",
    "currency": "USD",
    "type": "payment",
    "status": "completed",
    "createdAt": "2017-05-08T11:08:26+00:00",
    "updatedAt": "2017-05-08T11:08:34+00:00",
    "user": {
        "id": 17,
        "identifier": "1",
        "displayName": "User",
        "email": "user@example.com",
        "phone": "11111111111",
        "ip": "127.0.0.1",
        "locale": "ru"
    },
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "expirationMonth": 12,
        "expirationYear": 2034,
        "expiresAt": "2035-01-01T00:00:00+00:00",
        "holder": null,
        "scheme": "visa",
        "bankName": "EXTRAS TEST - VISA",
        "country": "US"
    }
}

Reverses a completed payment transaction.

HTTP request

POST https://api2.paysend.com/v1/transaction/reverse

Request parameters

Parameter Description
project
required
 Public key of your project.
id
optional, either id or order_id is required
 Identifier of a payment to reverse.
order_id
optional, either order_id or id is required
 Merchant’s order ID.
amount
required
 Integer or float number representing an amount to reverse.
comment
optional
 String describing reversal reason.
signature
required
 See the Authentication section.

Returns

Parameter Description
success
boolean
 Indicates whether request was successful.
id
bigint
 Identifier of a payment.
orderId
string
 Merchant’s order ID.
referenceId
bigint
 Reference transaction ID.
price
decimal
 Integer or float number representing payment price.
currency
string
 Three letter currency code in ISO 4217 format.
type
string
 Transaction type (payment, payout, exchange).
status
string
 Status of a current transaction.
fee
decimal
 Merchant’s fee.
card
object
 Card object
user
User object
 User.

Create new transaction

Example Request

curl https://api2.paysend.com/v1/transaction/create \
    -d signature=efe4077d4ea0d62fd62b65f1969184c048880183e9a342dd46e2101ff93b538a \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d user=1 \
    -d payment_method=web_money_wmz \
    -d price=5.99 \
    -d currency=USD \
    -d description=Test \
    -d success_url=https://example.com \
    -d fail_url=https://example.com

Example Response

{
    "id": "1530105654244093715",
    "amount": 5.99,
    "currency": "USD",
    "status": "opened"
}

Redirect user to https://checkout.paysend.com/confirm/{id}/ to continue with confirmation on the payment system side.

HTTP request

POST https://api2.paysend.com/v1/transaction/create

Request parameters

Parameter Description
project
required
 Public key of your project.
user
required
 Unique and unchangeable identifier of a user.
display_name
optional
 Full name or nickname of a user.
payment_method
required
 Key of a payment method. Possible values are: paypal, qiwi, yandex_money_wallet, yandex_money_wallet_v2, web_money_wme, web_money_wmz, web_money_wmr.
price
required
 Integer or decimal number representing payment amount.
currency
required
 Three letter currency code in ISO 4217 format.
email
optional
 Email address of a user.
ip
optional
 IP address of a user.
ua
optional
 User Agent string of a user. Max 255 symbols.
phone
optional
 Phone number of a user in international format, without the leading + and any separators. Required for “qiwi” payment method.
locale
optional
 Locale of a user in ISO 639-1 format.
order_id
optional
 Merchant’s order ID that will be returned back in a callback.
description
required
 String describing reversal reason.
success_url
required
 URL where to redirect user on success.
fail_url
required
 URL where to redirect user on fail.
signature
required
 See the Authentication section.

Returns

Parameter Description
id
string
 Identifier of a transaction.
amount
float
 Integer or float number representing an amount.
currency
string
 Three letter currency code in ISO 4217 format.
status
string
 Status of a current transaction.

Retrieve status of a transaction

Example Request

curl "https://api2.paysend.com/v1/transaction/status?\
    signature=06c4f84b49c3b42d6f4fb0486408f276b634bb97ec3c86a643aa64285cd841ed&\
    project=d55ad89070d6172cc0eeeecfdde2c554&\
    id=1472169801800314651"

Example Response

{
    "id":"1472169801800314651",
    "order_id":null,
    "price": 20,
    "fee": 0,
    "currency": "USD",
    "type":"payment",
    "status":"refunded",
    "original_status":"completed",
    "created_at":"2016-08-26T03:03:21+03:00",
    "updated_at":"2016-08-26T03:03:22+03:00"
}

Returns transaction details and status.

HTTP request

GET https://api2.paysend.com/v1/transaction/status

Request parameters

Parameter Description
project
required
 Public key of your project.
id
optional, either id or order_id is required
 Identifier of a transaction.
order_id
optional, either order_id or id is required
 Merchant’s order ID.
signature
required
 See the Authentication section.

Returns

Parameter Description
id
bigint
 Identifier of a payment.
order_id
string
 Merchant’s order ID.
price
decimal(12,2)
 Price of transaction.
fee
decimal(12,4)
 Merchant’s fee.
currency
string
 Currency of transaction.
type
string
 Type of transaction.
status
string
 Status of transaction including all other transaction effects (e.g. opened, completed, charged_back, refunded).
original_status
string
 Original status of transaction. The last status applied to a transaction itself (e.g. opened, authenticating, completed).
created_at
date in ISO 8601
 Date when transaction was created.
updated_at
date in ISO 8601
 Date when transaction was last updated (doesn’t include other transaction effects).

Transaction types

Type Description
deposit Funds are charged from the merchant.
payment Funds are charged from a user.
verification Verification transaction.
chargeback Chargeback of payment transaction. Funds are returned to a user. Penalty may apply.
refund Refund of payment transaction. Funds are returned to a user. Penalty may apply.
retrieval Retrieval of chargeback transaction. Funds are returned to merchant. Penalty may not be returned back.
exchange Exchange transaction.
payout Payout transaction.
settlement Settlement transaction.
penalty Penalty transaction.
rolling_reserve Rolling reserve transaction.

Transaction statuses

Status Description
opened Transaction is opened.
processing Transaction is processing.
waiting_approval Transaction is waiting for approve.
authenticating Transaction is authenticating.
authorized Transaction is authorized.
completed Transaction has completed successfully.
failed Transaction has failed.
cancelled Transaction has cancelled.
abandoned Transaction has abandoned.
refunded Transaction is reversed/refunded.
charged_back Chargeback has completed because of a started dispute.
retrieved Chargeback dispute is won. Funds taken with a chargeback are returned.
returned Returned rolling reserve.
verified Transaction is of type verification and has completed successfully. Funds in amount of 1 EUR were frozen and released to verify card.

Payout

Fetch available payout types

Example Request

curl https://api2.paysend.com/v1/payout-types?\
    project=d55ad89070d6172cc0eeeecfdde2c554

Example of Complete Response

{
   "success": true,
   "types": [
      {
         "id": 0,
         "key": "CREDIT_CARD",
         "label": "Credit Card"
      },
      {
         "id": 1,
         "key": "SEPA",
         "label": "Sepa"
      }
   ]
}

List of available payout types for merchant

HTTP request

GET https://api2.paysend.com/v1/payout-types

Request parameters

Parameter Description
project
required
 Public key of your project.

Returns

Parameter Description
success
boolean
 Indicates request was successful or not.
types
object
 Collection of payout type. See Payout-type object for details.

Fetch payout parameters

Example Request

curl https://api2.paysend.com/v1/payout-parameters?\
    project=d55ad89070d6172cc0eeeecfdde2c554&\
    type=0&\
    currency=RUB&\
    account=553691

Example of Complete Response

[
    {
        "name": "amount",
        "type": "text",
        "label": "Amount",
        "required": true
    },
    {
        "name": "phone",
        "type": "text",
        "label": "Phone",
        "required": true
    },
    {
        "name": "description",
        "type": "text",
        "label": "Description",
        "required": false
    }
]

List of required parameters. Payout parameters depend on (project, type, account, currency). This parameter names will be used in payout.

HTTP request

GET https://api2.paysend.com/v1/payout-parameters

Request parameters

Parameter Description
project
required
 Public key of your project.
type
required
 Id of Payout-type object. For fetch use Fetch available payout types
account
required
 Recipient’s account. If payout type equals to CREDIT_CARD then pass BIN (first 6 digit of credit card) otherwise pass it entirely.
currency
required
 Three letter currency code in ISO 4217 format.

Returns

Response will contain collection of Payout-parameter-control object.

Payout parameters

These are all available payout parameters. Use the method Fetch payout parameters to acquire the required additional parameters for your use case.

Parameter Description
firstName Remitter First Name.
lastName Remitter Last Name.
birthDate Remitter Birth Date (d.m.Y).
birthPlace Remitter Birth Date (d.m.Y).
country Remitter Country.
countryOfCitizenship Remitter Country Of Citizenship.
city Remitter City.
address Remitter Address.
postalCode Remitter Postal Code.
documentType Remitter Document Type. (passport, id)
documentIssuer Remitter Document Issuer.
documentSeries Remitter Document Series.
documentNumber Remitter Document Number.
documentIssuedAt Remitter Document Issued At.
documentValidUntil Remitter Document Valid Until.
remitterCardNumber Remitter Card Number.
remitterCardToken Remitter Card Token.
remitterCardExpirationMonth Remitter Card Token.
remitterCardExpirationYear Remitter Card Token.
remitterPhone Remitter Phone.
beneficiaryFirstName Beneficiary first name.
beneficiaryLastName Beneficiary Last Name.
beneficiaryLegalName Beneficiary Legal Name.
beneficiaryDocumentType Beneficiary Document Type. (passport, id)
beneficiaryDocumentIssuer Beneficiary Document Issuer.
beneficiaryDocumentSeries Beneficiary Document Series.
beneficiaryDocumentNumber Beneficiary Document Number.
beneficiaryDocumentIssuedAt Beneficiary Document Issued At.
beneficiaryDocumentValidUntil Beneficiary Document Valid Until.
cardExpirationDate Card Expiry date MM/YY. If required you have to pass it to cardToken.
description Description of payout transaction.
phone Phone Number.
cardHolder Card Holder.
fullName Full Name.
receiverBankBIC Bic/Swift.

Create payout

Example Request

curl https://api2.paysend.com/v1/payout \
    -d signature=8bcfd8f3056bdb00d5dc84ed4d6ae7b6198b64f5a36d4e82f5c9ebca52be4b40 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d type=0 \
    -d currency=RUB \
    -d amount=10 \
    -d description=payout \
    -d cardToken=4f2bb447726f0e759696c495024d6fda7706ca5b87eed431867f3f5410767a5f \
    -d phone=77777777777

Example of Complete Response

{
    "id": "1534974617313178347",
    "status": "processing",
    "success": true
}

Create new payout

HTTP request

POST https://api2.paysend.com/v1/payout

Common request parameters

Parameter Description
project
required
 Public key of your project.
type
required
 Id of Payout-type object. For fetch use Fetch available payout types.
account
optional
 Recipient’s account. Mostly required, but if payout type is CREDIT_CARD then account or cardToken can be used.
cardToken
optional
 Token of a credit card. Can be used instead of passing card number to account. See create card token.
amount
required
 Integer or float number representing payout price.
currency
required
 Three letter currency code in ISO 4217 format.
orderId
optional
 Merchant’s order ID.
signature
required
 Make sure that the signature sent with the callback is correct. See the Authentication section.

Each combination of payout type, account and currency may have it’s own list of additional parameters required to complete the payout, thus you have to acquire the list of required additional parameters using the method Fetch payout parameters. For all possible payout parameters, please consult Payout parameters.

Returns

Parameter Description
id
bigint
 Identifier of a payment.
success
boolean
 Indicates whether request was successful or not.
status
string
 Status of a transaction. See the Callback statuses section.

Balance

Get merchants balance

Example Request

curl https://api2.paysend.com/v1/balance?\
    project=d55ad89070d6172cc0eeeecfdde2c554\
    currency=USD\
    signature=d0aeccdcf5f66e8464ed584e50528530967cb7ef8a76e26935f8b3fafd3c634b

Example of Complete Response

{
    "amount":"100.00",
    "rolling_reserve":"0.20",
    "currency":"USD",
    "base_amount":"1286.27",
    "base_rolling_reserve":"0.00"
}

Get merchants balance by currency

HTTP request

GET https://api2.paysend.com/v1/balance

Request parameters

Parameter Description
project
required
 Public key of your project.
currency
string(3)
 Currency.
signature
required
 See the Authentication section.

Returns

Parameter Description
amount
string
 Available amount for operation.
rolling_reserve
string
 Rolling reserve.
currency
string
 Currency of balance.
base_amount
string
 Total amount in base currency.
base_rolling_reserve
string
 Base rolling reserve.

Transactions

Get transaction by id

Example Request

curl https://api2.paysend.com/v1/transactions/1569310086280783205?\
    project=d55ad89070d6172cc0eeeecfdde2c554\
    signature=d0aeccdcf5f66e8464ed584e50528530967cb7ef8a76e26935f8b3fafd3c634b

Example of Complete Response

{
    "id": "1569310086280783205",
    "orderId": "qwery12345",
    "referenceId": null,
    "price": "150.00",
    "fee": "0.0000",
    "currency": "RUB",
    "type": "payment",
    "status": "refunded",
    "method": "yandex_money",
    "originalStatus": "completed",
    "user": {
        "id": 17,
        "identifier": "1",
        "displayName": "LuxeMate",
        "email": "user@example.com",
        "phone": "7777777777",
        "ip": "127.0.0.1",
        "locale": "ru"
    },
    "createdAt": "2017-05-08T11:08:26+00:00",
    "updatedAt": "2017-05-08T11:08:34+00:00",
    "reason": null
}

Get transactions by order id

HTTP request

GET https://api2.paysend.com/v1/transactions/{id}

Request parameters

Parameter Description
id
required
 Transaction id.
project
required
 Public key of your project.
signature
required
 See the Authentication section.

Returns

Parameter Description
id
bigint
 Identifier of a payment.
orderId
string
 Merchant’s order ID.
price
decimal(12,2)
 Price of transaction.
fee
decimal(12,4)
 Merchant’s fee.
currency
string
 Currency of transaction.
type
string
 Type of transaction.
method
string
 Payment method.
status
string
 Status of transaction including all other transaction effects (e.g. opened, completed, charged_back, refunded).
originalStatus
string
 Original status of transaction. The last status applied to a transaction itself (e.g. opened, authenticating, completed).
createdAt
date in ISO 8601
 Date when transaction was created.
updatedAt
date in ISO 8601
 Date when transaction was last updated (doesn’t include other transaction effects).
user
User object
 User.
card
Card object
 User’s card.

Get transactions by order id

Example Request

curl https://api2.paysend.com/v1/transactions?\
    orderId=d55ad89070d6172cc0eeeecfdde2c554\
    project=d55ad89070d6172cc0eeeecfdde2c554\
    signature=d0aeccdcf5f66e8464ed584e50528530967cb7ef8a76e26935f8b3fafd3c634b

Example of Complete Response

{
    "totalCount": 1,
    "transactions": [
        {
            "id": "1569310086280783205",
            "orderId": "qwery12345",
            "referenceId": null,
            "price": "150.00",
            "fee": "0.0000",
            "currency": "RUB",
            "type": "payment",
            "status": "refunded",
            "method": "yandex_money",
            "originalStatus": "completed",
            "user": {
                "id": 17,
                "identifier": "1",
                "displayName": "LuxeMate",
                "email": "user@example.com",
                "phone": "7777777777",
                "ip": "127.0.0.1",
                "locale": "ru"
            },
            "createdAt": "2017-05-08T11:08:26+00:00",
            "updatedAt": "2017-05-08T11:08:34+00:00",
            "reason": null
        }
    ]
}

Get transactions by order id

HTTP request

GET https://api2.paysend.com/v1/transactions

Request parameters

Parameter Description
orderId
required
 Merchant’s order id.
project
required
 Public key of your project.
signature
required
 See the Authentication section.
status
string
 Filter by transaction status.
type
string
 Filter by transaction type.
created[from]
string
 Filter transaction created after.
created[to]
string
 Filter transaction created before.
updated[from]
string
 Filter transaction updated after.
updated[to]
string
 Filter transaction updated before.
page
string
 Page number.
limit
string
 Set limit transaction on page.

Returns

Parameter Description
totalCount
int
 Count of available transaction in the response.
transactions
Object
 Collection of transaction. Structure of transaction you can see in Transaction response section.
curl