SecurionPay API is REST based API that allows fast and easy integration. We use HTTP for transport and return all responses encoded as JSON.
To simplify integration and testing each account have two modes: test-mode and live-mode. Both modes can be active at the same time - each mode have separate set of public and secret keys. We ensure that data created with test-mode will never reach real customers and will never cost you any money.
API ENDPOINT
https://api.securionpay.com/
SecurionPay API uses "HTTP Basic authentication" for authentication. All requests to our API have to be authentication and all requests have to be made over HTTPS.
To authenticate you need to provide your "API Secret Key" as username and leave password blank. You can find your API keys in your account settings once you login to your account. It is important to keep your "API Secret Key" safe as it allows to perform many privileged operations on your behalf.
EXAMPLE REQUEST
curl https://api.securionpay.com/charges \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
Note: adding colon after API key will prevent curl from asking for password
SecurionPay API is using HTTP codes to indicate result of API call. Codes in range 2xx indicate success, codes in range 4xx indicate error on your side (something is wrong with your request) and codes in range 5xx indicate error on our side.
If request resulted in error then an error object is returned instead of normal response.
HTTP Status codes
200 OK - Successful request
400 Bad Request - Request has invalid data or is missing a required field
401 Unauthorized - Provided API key is missing or invalid
402 Payment failed - Request was valid but card processing has failed
404 Not Found - Requested object was not found
429 Too Many Requests - Requests hit the API too quickly
500, 502, 503, 504 Server error - Something went wrong on our side
invalid_request
- Request has invalid or missing parameterscard_error
- Card processing has failedgateway_error
- Something went wrong on our siderate_limit_error
- Requests hit the API too quicklytype=card_error
).
Possible values are:invalid_number
- The card number is not a valid card number.invalid_expiry_month
- The card's expiration month is invalid.invalid_expiry_year
- The card's expiration year is invalid.invalid_cvc
- Your card's security code is invalid.incorrect_cvc
- The card's security code failed verification.incorrect_zip
- The card's zip code failed verification.expired_card
- The card has expired.insufficient_funds
- The charge amount exceeds the available fund or the card's credit limit.lost_or_stolen
- The card is marked as lost or stolen.suspected_fraud
- The charge is suspected to be fraudulent.limit_exceeded
- You have exceeded defined limit.card_declined
- The card was declined for other reason.processing_error
- An error occurred while processing the card.blacklisted
- The card is blacklisted.expired_token
- The token has expired.authentication_required
- The charge requires authentication.do_not_try_again
- The card was declined and should not be retried.currency_not_supported
- Your account is not configured to process given currency.EXAMPLE ERROR RESPONSE
{
"error" : {
"type" : "card_error",
"code" : "invalid_number",
"message" : "The card number is not a valid card number."
}
}
Most of updatable objects have metadata
attribute that can be used to store custom pairs of key-value data.
This is useful for storing additional structured information associated with given object. Example would be to save user login together with a customer object that represents that user.
Each key must be unique within given metadata object. It is possible to store up to 255 characters in each key and each value.
EXAMPLE REQUEST
{
"email" : "[email protected]",
"metadata" : {
"key1" : "value1",
"key2" : "value2"
}
}
EXAMPLE RESPONSE
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"metadata" : {
"key1" : "value1",
"key2" : "value2"
}
}
Change represents payment made with a credit or a debit card.
null
if this charge is not associated with any customer.
null
if this charge is not associated with any subscription.
safe
, suspicious
or fraudulent
pending
- 3D Secure was not started or is in progresssuccessful
- 3D Secure was completed successfullyfailed
- 3D Secure is supported, but was not completed successfullynot_possible
- 3D Secure is not supported
frictionless
- Issuer authenticated the customer via frictionless flow.challenge
- Issuer authenticated the customer by showing a challenge window.code
attribute in error object.
EXAMPLE OBJECT
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "EUR",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"customerId" : null,
"captured" : true,
"refunded" : false,
"refunds" : [],
"disputed" : false,
"metadata" : {}
}
Creates a new charge object.
Capturing a charge object (either at creation or at late time) will result in charge of provided credit or debit card
If you are in test mode, then provided credit or debit card won't actually be charged, but everything else will work the same as in live mode.
customerId
field)
Successful request returns a charge object that represents created charge.
DEFINITION
POST https://api.securionpay.com/charges
EXAMPLE REQUEST
curl https://api.securionpay.com/charges \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "amount=499" \
-d "currency=EUR" \
-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe" \
-d "description=Example charge"
EXAMPLE RESPONSE
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "EUR",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
}
Retrieve an existing charge object.
Successful request returns a charge object.
DEFINITION
GET https://api.securionpay.com/charges/{CHARGE_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "EUR",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
}
Update an existing charge object.
Any not provided parameter will be left unchanged.
safe
, suspicious
, fraudulent
, in_progress
or unknown
Successful request returns a charge object that was updated.
DEFINITION
POST https://api.securionpay.com/charges/{CHARGE_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "description=New description"
EXAMPLE RESPONSE
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "EUR",
"description" : "New description",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
}
Capture a existing charge that was created with captured=false
attribute.
This is second part of two step payment flow.
Successful request returns a charge object that was captured.
DEFINITION
POST https://api.securionpay.com/charges/{CHARGE_ID}/capture
EXAMPLE REQUEST
curl https://api.securionpay.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q/capture \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X POST
EXAMPLE RESPONSE
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "EUR",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
}
List charge objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of charge objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/charges
EXAMPLE REQUEST
curl "https://api.securionpay.com/charges?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "EUR",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
},
{ ... },
{ ... }
],
"hasMore" : true
}
RETRIEVAL_REQUEST_NEW
RETRIEVAL_REQUEST_REPRESENTED
CHARGEBACK_NEW
CHARGEBACK_REPRESENTED_SUCCESSFULLY
CHARGEBACK_REPRESENTED_UNSUCCESSFULLY
FRAUDULENT
UNRECOGNIZED
DUPLICATE
SUBSCRIPTION_CANCELED
PRODUCT_NOT_RECEIVED
PRODUCT_UNACCEPTABLE
CREDIT_NOT_PROCESSED
GENERAL
EXAMPLE OBJECT
{
"objectType" : "dispute",
"created" : 1415896911,
"updated" : 1415896911,
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"amount" : 499,
"currency" : "EUR",
"acceptedAsLost" : false
}
Refund represents refund of a charge.
fraudulent
successful, failed
EXAMPLE OBJECT
{
"id" : "re_CNiqwdKHpX3o4SD4PWJxM5CF",
"created" : 1609325894,
"amount" : 100,
"currency" : "EUR",
"objectType" : "refund",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"reason" : "fraudulent",
"status" : "successful"
}
Refund an existing charge, which will result in funds being returned to the previously charged credit or debit card.
It is possible to only refund part of captured charge. This partial refund can be repeated for as long as the charge is not fully refunded.
Note that if there is an active subscription related with this charge, it won't be affected by this operation. If you want to cancel a subscription, you will need to make it in a separate request.
fraudulent
Successful request returns a refund object.
DEFINITION
POST https://api.securionpay.com/refunds
EXAMPLE REQUEST
curl https://api.securionpay.com/refunds \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "chargeId=char_ZNmWK4pUECfFQTY0N4WMKeh3&amount=499"
EXAMPLE RESPONSE
{
"id" : "re_CNiqwdKHpX3o4SD4PWJxM5CF",
"created" : 1609325894,
"amount" : 100,
"currency" : "EUR",
"objectType" : "refund",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"reason" : "fraudulent",
"status" : "successful"
}
Retrieve an existing refund object.
Successful request returns a refund object.
DEFINITION
GET https://api.securionpay.com/refunds/{REFUND_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/refunds/re_CNiqwdKHpX3o4SD4PWJxM5CF \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "re_CNiqwdKHpX3o4SD4PWJxM5CF",
"created" : 1609325894,
"amount" : 100,
"currency" : "EUR",
"objectType" : "refund",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"reason" : "fraudulent",
"status" : "successful"
}
List refund objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of refund objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/refunds
EXAMPLE REQUEST
curl "https://api.securionpay.com/refunds?chargeId=char_ZNmWK4pUECfFQTY0N4WMKeh3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "re_CNiqwdKHpX3o4SD4PWJxM5CF",
"created" : 1609325894,
"amount" : 100,
"currency" : "EUR",
"objectType" : "refund",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"reason" : "fraudulent",
"status" : "successful"
},
{ ... },
{ ... }
],
"hasMore" : true
}
Customers allows to store cards for later use and to perform automatically recurring charges. Customers are also useful for tracking charges that are associated with the same entity.
EXAMPLE OBJECT
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"description" : null,
"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"cards" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
],
"metadata" : { }
}
Creates a new customer object.
Successful request returns a customer object that represents created customer.
DEFINITION
POST https://api.securionpay.com/customers
EXAMPLE REQUEST
curl https://api.securionpay.com/customers \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "[email protected]" \
-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe"
EXAMPLE RESPONSE
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"cards" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
]
}
Retrieve an existing customer object.
Successful request returns a customer object.
DEFINITION
GET https://api.securionpay.com/customers/{CUSTOMER_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"cards" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
]
}
Update an existing customer object.
Any not provided parameter will be left unchanged.
Successful request returns a customer object that was updated.
DEFINITION
POST https://api.securionpay.com/customers/{CUSTOMER_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "[email protected]" \
-d "description=New description"
EXAMPLE RESPONSE
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"description" : "New description",
"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"cards" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
]
}
Deletes an existing customer object.
Successful request returns identifier of deleted customer object.
DEFINITION
DELETE https://api.securionpay.com/customers/{CUSTOMER_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
}
List customer objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of customer objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/customers
EXAMPLE REQUEST
curl "https://api.securionpay.com/customers?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"created" : 1415810511,
"objectType" : "customer",
"email" : "[email protected]",
"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"cards" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
]
},
{ ... },
{ ... }
],
"hasMore" : false
}
Card represents a credit or a debit card.
Cards are used to save a credit or a debit card data for later use. Cards can also be used to represent card data in other operations (for example to specify card data when creating a new change).
Visa
,
American Express
,
MasterCard
,
Maestro
,
Discover
,
JCB
,
Diners Club
,
Unknown
Credit Card
,
Debit Card
,
Unknown
checkFastCredit = true
.
Contains following attributes:
EXAMPLE OBJECT
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH",
"fastCredit" : {
"supported" : true,
"updated" : 1415811511
}
}
Creates a new card object.
There are three ways to create a new card object:
Successful request returns a card object that represents created card.
DEFINITION
POST https://api.securionpay.com/customers/{CUSTOMER_ID}/cards
EXAMPLE REQUEST
curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "id=tok_NGsyDoJQXop5Pqqi6HizbJTe"
EXAMPLE RESPONSE
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
Retrieve an existing card object.
Successful request returns a card object.
DEFINITION
GET https://api.securionpay.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
Update an existing card object.
Any not provided parameter will be left unchanged.
Successful request returns a card object that was updated.
DEFINITION
POST https://api.securionpay.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "cardholderName=Jane Doe"
-d "checkFastCredit=true"
EXAMPLE RESPONSE
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "Jane Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH",
"fastCredit" : {
"supported" : true,
"updated" : 1415811511
}
}
Deletes an existing card object.
If you delete card that is current default card then most recently added card will be used as new default card.
If you delete last card then default card will be set to null
.
Successful request returns identifier of deleted card object.
DEFINITION
DELETE https://api.securionpay.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
}
List card objects for given customer.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of card objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/customers/{CUSTOMER_ID}/cards
EXAMPLE REQUEST
curl "https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
{ ... },
{ ... }
],
"hasMore" : false
}
Subscription represents recurring payment that will result in charge to be automatically created for given customer. Frequency and amount of these automatic charges is defined by a plan.
Subscriptions are always billed to customer's current default card.
amount=100
used in subscription with
quantity=5
will result in changes with amount=500
.
false
then you need to manually capture
each charge created by this subscription.
trialing
- subscription was created from a plan with trial days and is still in the trial periodactive
- subscription is active and will be renewed after the end of a current billing cyclepast_due
- renewing of subscription has failedcanceled
- subscription was manually canceled, or all retry renew attempts have failedunpaid
- all retry renew attempts have failedincomplete
- first charge has failed on subscription creationcreated
if subscription plan was changed.
canceledAt
if subscription was canceled with
atPeriodEnd=true
.
true
then subscription will be canceled at end of current billing period.
EXAMPLE OBJECT
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 1,
"status" : "active",
"remainingBillingCycles" : null,
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"canceledAt" : null,
"endedAt" : null,
"trialStart" : null,
"trialEnd" : null,
"cancelAtPeriodEnd" : false,
"metadata" : {}
}
Creates a new subscription object.
false
then you need to manually capture
each charge created by this subscription.
Successful request returns a subscription object that represents created subscription.
DEFINITION
POST https://api.securionpay.com/subscriptions
EXAMPLE REQUEST
curl https://api.securionpay.com/subscriptions \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "planId=plan_bLu3vzO8yhAFhbxFEadm6HUV"
EXAMPLE RESPONSE
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 1,
"status" : "active",
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"cancelAtPeriodEnd" : false
}
Retrieve an existing subscription object.
Successful request returns a subscription object.
DEFINITION
GET https://api.securionpay.com/subscriptions/{SUBSCRIPTION_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 1,
"status" : "active",
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"cancelAtPeriodEnd" : false
}
Update an existing subscription object.
Any not provided parameter will be left unchanged.
false
then you need to manually capture
each charge created by this subscription.
-1
can be used to end trial immediately.
Successful request returns a subscription object that was updated.
DEFINITION
POST https://api.securionpay.com/subscriptions/{SUBSCRIPTION_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "quantity=5"
EXAMPLE RESPONSE
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 5,
"status" : "active",
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"cancelAtPeriodEnd" : false
}
Cancels an existing subscription.
Successful request returns a subscription object that was canceled.
DEFINITION
DELETE https://api.securionpay.com/subscriptions/{SUBSCRIPTION_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE REQUEST (with atPeriodEnd)
curl https://api.securionpay.com/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5?atPeriodEnd=true \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 1,
"status" : "canceled",
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"canceledAt" : 1415982979,
"endedAt" : 1415982979,
"cancelAtPeriodEnd" : false
}
List subscription objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of subscription objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/subscriptions
EXAMPLE REQUEST
curl "https://api.securionpay.com/subscriptions?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
"created" : 1415982733,
"objectType" : "subscription",
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"quantity" : 1,
"status" : "active",
"start" : 1415982733,
"currentPeriodStart" : 1415982733,
"currentPeriodEnd" : 1416846733,
"cancelAtPeriodEnd" : false
},
{ ... },
{ ... }
],
"hasMore" : true
}
Plan represents automatically recurring charge.
Plans are used when a subscription is created for a customer to define how often and for how much given customer will be charged.
hour
,
day
,
week
,
month
,
year
interval=day
and intervalCount=10
will result in charge every 10 days.
null
means no limit on number of charges.
billingCycles
)
it will move to plan defined by this attribute.
EXAMPLE OBJECT
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1415973454,
"objectType" : "plan",
"amount" : 499,
"currency" : "EUR",
"interval" : "day",
"intervalCount" : 10,
"billingCycles" : null,
"name" : "Example plan",
"trialPeriodDays" : null,
"recursTo" : null,
"metadata" : {}
}
Creates a new plan object.
hour
,
day
,
week
,
month
,
year
interval=day
and intervalCount=10
will result in charge every 10 days.
null
means no limit on number of charges.
billingCycles
)
it will move to plan defined by this attribute.
Successful request returns a plan object that represents created plan.
DEFINITION
POST https://api.securionpay.com/plans
EXAMPLE REQUEST
curl https://api.securionpay.com/plans \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "amount=499" \
-d "currency=EUR" \
-d "interval=day" \
-d "intervalCount=10" \
-d "name=Example plan"
EXAMPLE RESPONSE
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1415973454,
"objectType" : "plan",
"amount" : 499,
"currency" : "EUR",
"interval" : "day",
"intervalCount" : 10,
"name" : "Example plan",
"trialPeriodDays" : 0
}
Retrieve an existing plan object.
Successful request returns a plan object.
DEFINITION
GET https://api.securionpay.com/plans/{PLAN_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1415973454,
"objectType" : "plan",
"amount" : 499,
"currency" : "EUR",
"interval" : "day",
"intervalCount" : 10,
"name" : "Example plan",
"trialPeriodDays" : 0
}
Update an existing plan object.
Any not provided parameter will be left unchanged.
Changing amount
or currency
of a plan
will only affect future rebills of all subscriptions that are using this plan.
Successful request returns a plan object that was updated.
DEFINITION
POST https://api.securionpay.com/plans/{PLAN_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "name=New plan"
EXAMPLE RESPONSE
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1415973454,
"objectType" : "plan",
"amount" : 499,
"currency" : "EUR",
"interval" : "day",
"intervalCount" : 10,
"name" : "New plan",
"trialPeriodDays" : 0
}
Deletes an existing plan object.
Note that when you delete a plan then existing subscriptions will continue to be charged until they are canceled.
Successful request returns identifier of deleted plan object.
DEFINITION
DELETE https://api.securionpay.com/plans/{PLAN_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
}
List plan objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of plan objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/plans
EXAMPLE REQUEST
curl "https://api.securionpay.com/plans?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1415973454,
"objectType" : "plan",
"amount" : 499,
"currency" : "EUR",
"interval" : "day",
"intervalCount" : 10,
"name" : "Example plan",
"trialPeriodDays" : 0
},
{ ... },
{ ... }
],
"hasMore" : true
}
Events can be used to get notification when something interesting has happened.
For example creation of new successful charge will result in CHARGE_SUCCEEDED
event.
We provide API methods to retrieve single event and to list events. It is also possible get notifications about new events by using Webhooks.
type=CHARGE_SUCCEEDED
will have a charge object as value of this attribute.
EXAMPLE OBJECT
{
"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
"created" : 1416305114,
"objectType" : "event",
"type" : "CHARGE_SUCCEEDED",
"data" : {
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "EUR",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
},
"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
}
Retrieve an existing event object.
Successful request returns an event object.
DEFINITION
GET https://api.securionpay.com/events/{EVENT_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/events/event_EY7CzyQiffJykW8rC5wSRnAj \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
"created" : 1416305114,
"objectType" : "event",
"type" : "CHARGE_SUCCEEDED",
"data" : {
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "EUR",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
},
"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
}
List event objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of event objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/events
EXAMPLE REQUEST
curl "https://api.securionpay.com/events?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
"created" : 1416305114,
"objectType" : "event",
"type" : "CHARGE_SUCCEEDED",
"data" : {
"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
"created" : 1415810511,
"objectType" : "charge",
"amount" : 499,
"currency" : "EUR",
"description" : "Example charge",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : false
},
"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
},
{ ... },
{ ... }
],
"hasMore" : true
}
CHARGE_SUCCEEDED
CHARGE_FAILED
CHARGE_UPDATED
CHARGE_CAPTURED
CHARGE_REFUNDED
CHARGE_DISPUTE_CREATED
CHARGE_DISPUTE_UPDATED
CHARGE_DISPUTE_WON
CHARGE_DISPUTE_LOST
CHARGE_DISPUTE_FUNDS_WITHDRAWN
CHARGE_DISPUTE_FUNDS_RESTORED
CUSTOMER_CREATED
CUSTOMER_UPDATED
CUSTOMER_DELETED
CUSTOMER_CARD_CREATED
CUSTOMER_CARD_UPDATED
CUSTOMER_CARD_DELETED
CUSTOMER_SUBSCRIPTION_CREATED
CUSTOMER_SUBSCRIPTION_UPDATED
CUSTOMER_SUBSCRIPTION_DELETED
PLAN_CREATED
PLAN_UPDATED
PLAN_DELETED
CROSS_SALE_OFFER_CREATED
CROSS_SALE_OFFER_UPDATED
CROSS_SALE_OFFER_DELETED
CREDIT_SUCCEEDED
CREDIT_FAILED
CREDIT_UPDATED
FRAUD_WARNING_CREATED
FRAUD_WARNING_UPDATED
PAYOUT_CREATED
PAYOUT_UPDATED
Tokens are used to represent card in situation where you don't want to process or store card sensitive data on your servers. Tokens can be easily created directly in a browser with use of custom form, but you can also create tokens in other environments (for example in mobile application).
Tokens can be created with use of either "API Public Key" or "API Secret Key". You can safely embedded your "API Public Key" in JavaScript or in downloadable applications (like iPhone or Android apps), so you can easily create tokens directly from these applications.
Note that tokens are meant to be used as temporary representation of card data and each token can be used only once. You should not store tokens for long periods of time - if you want to store card for later use you should use token to either create new customer or add new card to existing customer.
Visa
,
American Express
,
MasterCard
,
Discover
,
JCB
,
Diners Club
,
Unknown
Credit Card
,
Debit Card
,
Unknown
pending
- 3D Secure was not started or is in progresssuccessful
- 3D Secure was completed successfullyfailed
- 3D Secure is supported, but was not completed successfullynot_possible
- 3D Secure is not supported
frictionless
- Issuer authenticated the customer via frictionless flow.challenge
- Issuer authenticated the customer by showing a challenge window.EXAMPLE OBJECT
{
"id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
"created" : 1415810511,
"objectType" : "token",
"first6" : "42424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"brand" : "Visa",
"type" : "Credit Card",
"country" : "CH",
"used" : true,
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
}
Creates a new token object.
This method can be called with either "API Public Key" or "API Secret Key".
Successful request returns a token object that represents given card details.
DEFINITION
POST https://api.securionpay.com/tokens
EXAMPLE REQUEST
curl https://api.securionpay.com/tokens \
-u pu_test_WVMFC9GFuvm54b0uorifKkCh: \
-d "number=4242424242424242" \
-d "expMonth=11" \
-d "expYear=2022" \
-d "cvc=123" \
-d "cardholderName=John Doe"
EXAMPLE RESPONSE
{
"id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
"created" : 1415810511,
"objectType" : "token",
"first6" : "42424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"brand" : "Visa",
"type" : "Credit Card",
"country" : "CH",
"used" : false
}
Retrieve an existing token object.
Successful request returns a token object.
DEFINITION
GET https://api.securionpay.com/tokens/{TOKEN_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/tokens/tok_NGsyDoJQXop5Pqqi6HizbJTe \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
"created" : 1415810511,
"objectType" : "token",
"first6" : "42424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"brand" : "Visa",
"type" : "Credit Card",
"country" : "CH",
"used" : false
}
Initialize a new 3D Secure authentication process.
Generally (apart from few specialized use-cases) it is not recommended to initialized 3D Secure from API. You should use our custom form or checkout integration that already supports 3D Secure authentication.
To complete 3D Secure process initialized using this API call you must:
enrolled
filed in response is equal to true
redirectUrl
or display that URL in an <iframe> tag.returnUrl
token
to create chargesuccessful
or failed
Successful request returns object with following attributes:
DEFINITION
POST https://api.securionpay.com/3d-secure
EXAMPLE REQUEST
curl https://api.securionpay.com/3d-secure \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "amount=499" \
-d "currency=EUR" \
-d "card[number]=4012001800000016" \
-d "card[expMonth]=11" \
-d "card[expYear]=2022" \
-d "card[cvc]=123" \
-d "returnUrl=https://example.com/"
EXAMPLE RESPONSE
{
"enrolled": true,
"version": "2.2.0",
"redirectUrl": "https://api.securionpay.com/3d-secure/start/35WSIRL2Qm1JKsDXMohFVhGVj5AFptAhuN7Sa0oQ",
"token": {
"id": "tok_RBZVaNlPj70nNIQ2cIB2lYMI",
"created": 1634561057,
"objectType": "token",
"first6": "401200",
"last4": "0016",
"fingerprint": "8bTF2cbb2ccGr7ws",
"expMonth": "11",
"expYear": "2022",
"brand": "Visa",
"type": "Credit Card",
"country": "CH",
"used": false,
"threeDSecureInfo": {
"amount": 499,
"currency": "EUR",
"enrolled": true,
"liabilityShift": "failed",
"version": "2.2.0",
"authenticationFlow": null
}
}
}
Blacklist can be used to block unwanted charges.
Blacklist contains Blacklist Rule objects.
Each such object represents single condition - if request to create a new charge
matches this condition then it will fail - resulting in error response
with code=blacklisted
.
ruleType=fingerprint
.
ruleType=ip_address
.
ruleType=ip_country
.
ruleType=metadata
.
ruleType=metadata
.
ruleType=email
.
ruleType=user_agent
.
ruleType=accept_language
.
ruleType=card_country
.
ruleType=card_bin
.
ruleType=card_issuer
.
EXAMPLE OBJECT
{
"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
"created" : 1429282784,
"objectType" : "blacklistRule",
"ruleType" : "fingerprint",
"fingerprint" : "e3d8suyIDgFg3pE7"
}
Creates a new blacklist rule object.
ruleType=fingerprint
.
ruleType=fingerprint
.
If card number is provided then it will be automatically converted to fingerprint.
When creating fingerprint
rule then you must provide either fingerprint or card number, but not both.
ruleType=ip_address
.
ruleType=ip_country
.
ruleType=metadata
.
ruleType=metadata
.
ruleType=email
.
ruleType=user_agent
.
ruleType=accept_language
.
ruleType=card_country
.
ruleType=card_bin
.
ruleType=card_issuer
.
Successful request returns a blacklist rule object that represents created blacklist rule.
DEFINITION
POST https://api.securionpay.com/blacklist
EXAMPLE REQUEST
curl https://api.securionpay.com/blacklist \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "ruleType=fingerprint" \
-d "fingerprint=e3d8suyIDgFg3pE7"
EXAMPLE RESPONSE
{
"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
"created" : 1429282784,
"objectType" : "blacklistRule",
"ruleType" : "fingerprint",
"fingerprint" : "e3d8suyIDgFg3pE7"
}
Retrieve an existing blacklist rule object.
Successful request returns a blacklist Rule object.
DEFINITION
GET https://api.securionpay.com/blacklist/{BLACKLIST_RULE_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/blacklist/blr_O3y7VyxbszuezuDNjuBsExUf \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
"created" : 1429282784,
"objectType" : "blacklistRule",
"ruleType" : "fingerprint",
"fingerprint" : "e3d8suyIDgFg3pE7"
}
Deletes an existing blacklist rule object.
Successful request returns identifier of deleted blacklist rule object.
DEFINITION
DELETE https://api.securionpay.com/blacklist/{BLACKLIST_RULE_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/blacklist/blr_O3y7VyxbszuezuDNjuBsExUf \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
}
List blacklist rule objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of blacklist rule objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/blacklist
EXAMPLE REQUEST
curl "https://api.securionpay.com/blacklist?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
"created" : 1429282784,
"objectType" : "blacklistRule",
"ruleType" : "fingerprint",
"fingerprint" : "e3d8suyIDgFg3pE7"
},
{ ... },
{ ... }
],
"hasMore" : true
}
Checkout Request is used to define action that will be executed after customer has provided his card data in Checkout.
Checkout Request can define either single charge or automatically recurring subscription. If you already have customer object that represents your customer then you can include its identifier in Checkout Request so that created charge or subscription will be automatically assigned to that customer. If identifier of existing customer is not provided in Checkout Request then new customer object will be automatically created.
Creating Checkout Request can be done offline (without a need to communicate with SecurionPay servers). All you need to do is to sign Checkout Request object with your secret key - see signing a Checkout Request.
min
and max
attributes that defines valid range
for custom amount that is provided by customer.
amountOptions
attribute will result in Checkout that have buttons
with predefined amounts that customer can choose from.
Providing customAmount
attribute will result in Checkout that have input field
where customer can type any amount (but that amount must be within specified min/max range).
Providing both of these attributes at the same time will result in Checkout that have
both buttons with predefined amounts and input field to provide other custom amount.
EXAMPLE CHECKOUT REQUEST (with charge)
{
"charge" : {
"amount" : 499,
"currency" : "EUR"
},
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"rememberMe" : true
}
EXAMPLE CHECKOUT REQUEST (with subscription)
{
"subscription" : {
"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV"
},
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"rememberMe" : true
}
EXAMPLE CHECKOUT REQUEST (with custom charge)
{
"customCharge" : {
"amountOptions" : [100, 200, 500, 1000, 2000],
"customAmount" : {
"min" : 100,
"max" : 5000
},
"currency":"EUR"
},
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"rememberMe" : true
}
Checkout Request signature is created using HMAC with SHA256 using Checkout Request JSON and your secret key.
Signed Checkout Request is created by concatenating signature, pipe character (|
)
and Checkout Request JSON and then encoding it with BASE64.
Complete formula for signing checkout request:
$signed_checkout_request = base64( hmac_sha256( $checkout_request, $private_key ) + "|" + $checkout_request )
EXAMPLE SIGNING
export checkout_request='{"charge":{"amount":499,"currency":"EUR"}}'
export signature=`echo -n "$checkout_request" | openssl dgst -sha256 -hmac 'pr_test_tXHm9qV9qV9bjIRHcQr9PLPa' | sed 's/^.* //'`
echo -n "$signature|$checkout_request" | base64
EXAMPLE SIGNED CHECKOUT REQUEST
Y2Y5Y2UyZDgzMzFjNTMxZjgzODlhNjE2YTE4Zjk1NzhjMTM0Yjc4NGRhYjVjYjdlNGI1OTY0ZTc3OTBmMTczY3x7ImNoYXJnZSI6eyJhbW91bnQiOjQ5OSwiY3VycmVuY3kiOiJFVVIifX0=
Cross-sale offers can be used in Checkout to display additional offers after the main transaction was successfully completed.
Each cross-sale offer must define either charge or subscription that will be created when cross-sale offer is bought.
Cross-sale offers displayed in Checkout must be specified in a Checkout Request. You can always use your own cross-sale offers, but it is also possible to use cross-sale offers from your partners (merchants that were added to your partners list) - as long as these cross-sale offers are visible for you.
Charge or subscription created with cross-sale can be done using different MID then the MID that was used to do the main transaction. Main transaction is always done on MID of merchant that initiated checkout (the same as in Checkout without cross-sale offers). Cross-sale offer charge is always done on MID of the merchant that is the owner (creator) of that cross-sale offer.
When charge is create as result of buying a cross-sale offer then:
That way both partners (the one that opened Checkout for his customer and the one that is owner of cross-sale offer that was bought after checkout) will be informed that cross-sale took place.
image_and_text
,
text_only
.
visibleForAllPartners
- when offer is visible for all partners then this attribute has no effect.
EXAMPLE OBJECT
{
"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
"created" : 1442323521,
"objectType" : "crossSaleOffer",
"charge" : {
"amount" : 499,
"currency" : "EUR",
"capture" : true
},
"template" : "image_and_text",
"title" : "Buy 1000 gold coins",
"description" : "And get another 1000 for free",
"imageUrl" : "https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J/images/img_sTk23tRerAj1mwkzL8s3p5Oj",
"companyName" : "SecurionPay",
"companyLocation" : "CH",
"termsAndConditionsUrl" : "https://securionpay.com/docs/terms",
"visibleForAllPartners" : true
}
Creates a cross-sale offer object.
image_and_text
,
text_only
.
.png
, .jpeg
and .gif
.
Recommended image size is 247 × 156 pixels (if image size is different then image will be scaled to that size).
This image will be displayed when this offer is shown in Checkout.
visibleForAllPartners
- when offer is visible for all partners then this parameter has no effect.
Successful request returns a cross-sale offer object that represents created cross-sale offer.
DEFINITION
POST https://api.securionpay.com/cross-sale-offers
EXAMPLE REQUEST
curl https://api.securionpay.com/cross-sale-offers \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "charge[amount]=499" \
-d "charge[currency]=EUR" \
-d "template=image_and_text" \
-d "title=Buy 1000 gold coins" \
-d "description=And get another 1000 for free" \
-d "imageData=iVBORw0KGgoAAAANSUhEUgAAAB4AAAAeCAYAAAA7MK6iAAAAMUlEQVRIx%2B3NsQ0AMAzDMKf%2F%2F5yeUG9dqFkAZ5NN0VRXP558CgwGg8FgMBgMBoPB7y7UlAQ6IWgPUwAAAABJRU5ErkJggg==" \
-d "companyName=SecurionPay" \
-d "companyLocation=CH" \
-d "termsAndConditionsUrl=https://securionpay.com/docs/terms" \
-d "visibleForAllPartners=true"
EXAMPLE RESPONSE
{
"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
"created" : 1442323521,
"objectType" : "crossSaleOffer",
"charge" : {
"amount" : 499,
"currency" : "EUR",
"capture" : true
},
"template" : "image_and_text",
"title" : "Buy 1000 gold coins",
"description" : "And get another 1000 for free",
"imageUrl" : "https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J/images/img_sTk23tRerAj1mwkzL8s3p5Oj",
"companyName" : "SecurionPay",
"companyLocation" : "CH",
"termsAndConditionsUrl" : "https://securionpay.com/docs/terms",
"visibleForAllPartners" : true
}
Retrieve an existing cross-sale offer object.
Successful request returns a cross-sale offer object.
DEFINITION
GET https://api.securionpay.com/cross-sale-offers/{CROSS_SALE_OFFER_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
"created" : 1442323521,
"objectType" : "crossSaleOffer",
"charge" : {
"amount" : 499,
"currency" : "EUR",
"capture" : true
},
"template" : "image_and_text",
"title" : "Buy 1000 gold coins",
"description" : "And get another 1000 for free",
"imageUrl" : "https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J/images/img_sTk23tRerAj1mwkzL8s3p5Oj",
"companyName" : "SecurionPay",
"companyLocation" : "CH",
"termsAndConditionsUrl" : "https://securionpay.com/docs/terms",
"visibleForAllPartners" : true
}
Update an existing cross-sale offer object.
Any not provided parameter will be left unchanged.
image_and_text
,
text_only
.
.png
, .jpeg
and .gif
.
Recommended image size is 247 × 156 pixels (if image size is different then image will be scaled to that size).
This image will be displayed when this offer is shown in Checkout.
visibleForAllPartners
- when offer is visible for all partners then this parameter has no effect.
Successful request returns a cross-sale offer object that was updated.
DEFINITION
POST https://api.securionpay.com/cross-sale-offers/{CROSS_SALE_OFFER_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "title=Buy 500 gems"
EXAMPLE RESPONSE
{
"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
"created" : 1442323521,
"objectType" : "crossSaleOffer",
"charge" : {
"amount" : 499,
"currency" : "EUR",
"capture" : true
},
"template" : "image_and_text",
"title" : "Buy 500 gems",
"description" : "And get another 1000 for free",
"imageUrl" : "https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J/images/img_sTk23tRerAj1mwkzL8s3p5Oj",
"companyName" : "SecurionPay",
"companyLocation" : "CH",
"termsAndConditionsUrl" : "https://securionpay.com/docs/terms",
"visibleForAllPartners" : true
}
Deletes an existing cross-sale offer object.
Successful request returns identifier of deleted cross-sale offer object.
DEFINITION
DELETE https://api.securionpay.com/cross-sale-offers/{CROSS_SALE_OFFER_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X DELETE
EXAMPLE RESPONSE
{
"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
}
List cross-sale offer objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampself
can be used to return only your offers.
id=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of cross-sale offer objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/cross-sale-offers
EXAMPLE REQUEST
curl "https://api.securionpay.com/cross-sale-offers?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
"created" : 1442323521,
"objectType" : "crossSaleOffer",
"charge" : {
"amount" : 499,
"currency" : "EUR",
"capture" : true
},
"template" : "image_and_text",
"title" : "Buy 1000 gold coins",
"description" : "And get another 1000 for free",
"imageUrl" : "https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J/images/img_sTk23tRerAj1mwkzL8s3p5Oj",
"companyName" : "SecurionPay",
"companyLocation" : "CH",
"termsAndConditionsUrl" : "https://securionpay.com/docs/terms",
"visibleForAllPartners" : true
},
{ ... },
{ ... }
],
"hasMore" : true
}
Credit represents funds transfer to a card.
This feature is available for selected business models only. Please contact [email protected] to find out more.
null
if this credit is not associated with any customer.
pending
- 3D Secure was not started or is in progresssuccessful
- 3D Secure was completed successfullyfailed
- 3D Secure is supported, but was not completed successfullynot_possible
- 3D Secure is not supported
frictionless
- Issuer authenticated the customer via frictionless flow.challenge
- Issuer authenticated the customer by showing a challenge window.code
attribute in error object.
EXAMPLE OBJECT
{
"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
"created" : 1415810511,
"objectType" : "credit",
"amount" : 499,
"currency" : "EUR",
"description" : "Example credit",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH",
"fastCredit" : {
"supported" : true,
"updated" : 1415811511
}
},
"customerId" : null,
"fast" : true,
"metadata" : {}
}
Creates a new credit object.
If you are in test mode, then provided card won't receive any funds, but everything else will work the same as in live mode.
This feature is available for selected business models only. Please contact [email protected] to find out more.
customerId
field)
Successful request returns a credit object that represents created credit.
DEFINITION
POST https://api.securionpay.com/credits
EXAMPLE REQUEST
curl https://api.securionpay.com/credits \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "amount=499" \
-d "currency=EUR" \
-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe" \
-d "description=Example credit"
EXAMPLE RESPONSE
{
"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
"created" : 1415810511,
"objectType" : "credit",
"amount" : 499,
"currency" : "EUR",
"description" : "Example credit",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
}
Retrieve an existing credit object.
This feature is available for selected business models only. Please contact [email protected] to find out more.
Successful request returns a credit object.
DEFINITION
GET https://api.securionpay.com/credits/{CREDIT_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/credits/cr_OwM7B3WWha5SIfjNSw2eUqVb \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
"created" : 1415810511,
"objectType" : "credit",
"amount" : 499,
"currency" : "EUR",
"description" : "Example credit",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
}
Update an existing credit object.
Any not provided parameter will be left unchanged.
This feature is available for selected business models only. Please contact [email protected] to find out more.
Successful request returns a credit object that was updated.
DEFINITION
POST https://api.securionpay.com/credits/{CREDIT_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/credits/cr_OwM7B3WWha5SIfjNSw2eUqVb \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "description=New description"
EXAMPLE RESPONSE
{
"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
"created" : 1415810511,
"objectType" : "credit",
"amount" : 499,
"currency" : "EUR",
"description" : "New description",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
}
List credit objects.
This feature is available for selected business models only. Please contact [email protected] to find out more.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of credit objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/credits
EXAMPLE REQUEST
curl "https://api.securionpay.com/credits?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
"created" : 1415810511,
"objectType" : "credit",
"amount" : 499,
"currency" : "EUR",
"description" : "Example credit",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
}
},
{ ... },
{ ... }
],
"hasMore" : true
}
Dispute is created when a customer questions your charge with their bank or credit card company. When this happens you have an opportunity to respond by providing evidences that the charge is legitimate.
RETRIEVAL_REQUEST_NEW
- retrieval request, response neededRETRIEVAL_REQUEST_RESPONSE_UNDER_REVIEW
- retrieval request, response under reviewRETRIEVAL_REQUEST_REPRESENTED
- retrieval request, successfully representedCHARGEBACK_NEW
- chargeback, response neededCHARGEBACK_RESPONSE_UNDER_REVIEW
- chargeback, response under reviewCHARGEBACK_REPRESENTED_SUCCESSFULLY
- chargeback, dispute wonCHARGEBACK_REPRESENTED_UNSUCCESSFULLY
- chargeback, dispute lostFRAUDULENT
,
UNRECOGNIZED
,
DUPLICATE
,
SUBSCRIPTION_CANCELED
,
PRODUCT_NOT_RECEIVED
,
PRODUCT_UNACCEPTABLE
,
CREDIT_NOT_PROCESSED
,
GENERAL
EXAMPLE RESPONSE
{
"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
"created" : 1489571590,
"objectType" : "dispute",
"updated" : 1489571590,
"amount" : 1000,
"currency" : "EUR",
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"acceptedAsLost" : false,
"charge" : {
"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
"created" : 1489571590,
"objectType" : "charge",
"amount" : 0,
"currency" : "EUR",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : true
},
"evidence" : {
"productDescription" : "Exclusive black shoes",
"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
},
"evidenceDetails" : {
"hasEvidence" : true,
"submissionCount" : 1
}
}
EXAMPLE RESPONSE
{
"productDescription" : null,
"customerName" : null,
"customerEmail" : null,
"customerPurchaseIp" : null,
"customerSignature" : null,
"billingAddress" : null,
"receipt" : null,
"customerCommunication" : null,
"serviceDate" : null,
"serviceDocumentation" : null,
"duplicateChargeId" : null,
"duplicateChargeDocumentation" : null,
"duplicateChargeExplanation" : null,
"refundPolicy" : null,
"refundPolicyDisclosure" : null,
"refundRefusalExplanation" : null,
"cancellationPolicy" : null,
"cancellationPolicyDisclosure" : null,
"cancellationRefusalExplanation" : null,
"accessActivityLogs" : null,
"shippingAddress" : null,
"shippingDate" : null,
"shippingCarrier" : null,
"shippingTrackingNumber" : null,
"shippingDocumentation" : null,
"uncategorizedText" : null,
"uncategorizedFile" : null
}
Retrieve an existing dispute object.
Successful request returns a dispute object.
DEFINITION
GET https://api.securionpay.com/disputes/{DISPUTE_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/disputes/disp_2nayTQXBBjaVEPVtCwGCbqOj \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
"created" : 1489571590,
"objectType" : "dispute",
"updated" : 1489571590,
"amount" : 1000,
"currency" : "EUR",
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"acceptedAsLost" : false,
"charge" : {
"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
"created" : 1489571590,
"objectType" : "charge",
"amount" : 0,
"currency" : "EUR",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : true
},
"evidence" : {
"productDescription" : "Exclusive black shoes",
"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
},
"evidenceDetails" : {
"hasEvidence" : true,
"submissionCount" : 1
}
}
Update an existing dispute object.
Any not provided parameter will be left unchanged.
Successful request returns a dispute object.
DEFINITION
POST https://api.securionpay.com/disputes/{DISPUTE_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/disputes/disp_2nayTQXBBjaVEPVtCwGCbqOj \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-d "evidence[productDescription]=Exclusive black shoes" \
-d "evidence[customerCommunication]=file_2nayTQXBBjaVEPVtCwGCbqOj"
EXAMPLE RESPONSE
{
"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
"created" : 1489571590,
"objectType" : "dispute",
"updated" : 1489571590,
"amount" : 1000,
"currency" : "EUR",
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"acceptedAsLost" : false,
"charge" : {
"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
"created" : 1489571590,
"objectType" : "charge",
"amount" : 0,
"currency" : "EUR",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : true
},
"evidence" : {
"productDescription" : "Exclusive black shoes",
"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
},
"evidenceDetails" : {
"hasEvidence" : true,
"submissionCount" : 1
}
}
Closing the dispute indicates that you do not want to submit any evidence and that you are acknowledging it as lost.
Successful request returns identifier of closed dispute object.
DEFINITION
POST https://api.securionpay.com/disputes/{DISPUTE_ID}/close
EXAMPLE REQUEST
curl https://api.securionpay.com/disputes/disp_2nayTQXBBjaVEPVtCwGCbqOj/close \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-X POST
EXAMPLE RESPONSE
{
"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
"created" : 1489571590,
"objectType" : "dispute",
"updated" : 1489571590,
"amount" : 1000,
"currency" : "EUR",
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"acceptedAsLost" : false,
"charge" : {
"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
"created" : 1489571590,
"objectType" : "charge",
"amount" : 0,
"currency" : "EUR",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : true
},
"evidence" : {
"productDescription" : "Exclusive black shoes",
"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
},
"evidenceDetails" : {
"hasEvidence" : true,
"submissionCount" : 1
}
}
List dispute objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns list of a dispute object.
DEFINITION
POST https://api.securionpay.com/disputes
EXAMPLE REQUEST
curl https://api.securionpay.com/disputes \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list": [{
"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
"created" : 1489571590,
"objectType" : "dispute",
"updated" : 1489571590,
"amount" : 1000,
"currency" : "EUR",
"status" : "CHARGEBACK_NEW",
"reason" : "GENERAL",
"acceptedAsLost" : false,
"charge" : {
"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
"created" : 1489571590,
"objectType" : "charge",
"amount" : 0,
"currency" : "EUR",
"card" : {
"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
"created" : 1415810511,
"objectType" : "card",
"first6" : "424242",
"last4" : "4242",
"fingerprint" : "e3d8suyIDgFg3pE7",
"expMonth" : "11",
"expYear" : "2022",
"cardholderName" : "John Doe",
"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
"brand" : "Visa",
"type" : "Credit Card",
"issuer" : "Card Issuer Name",
"country" : "CH"
},
"captured" : true,
"refunded" : false,
"disputed" : true
},
"evidence" : {
"productDescription" : "Exclusive black shoes",
"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
},
"evidenceDetails" : {
"hasEvidence" : true,
"submissionCount" : 1
}
}]
}
File Upload objects are created by uploading a binary file (like image or PDF document) to SecurionPay. Such uploaded file can then be used in other API request by providing its identifier.
Note that for file upload uses different API endpoint: https://uploads.securionpay.com.
dispute_evidence
.
pdf
, jpg
, png
.
EXAMPLE RESPONSE
{
"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
"created" : 1415810511,
"objectType" : "file_upload",
"purpose" : "dispute_evidence",
"size" : 28461,
"type" : "jpg"
}
Creates a new file upload object.
dispute_evidence
Successful request returns a file upload object that represents uploaded file.
DEFINITION
POST https://uploads.securionpay.com/files
EXAMPLE REQUEST
curl https://uploads.securionpay.com/files \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
-F "purpose=dispute_evidence" \
-F file="@example-file.jpg"
EXAMPLE RESPONSE
{
"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
"created" : 1415810511,
"objectType" : "file_upload",
"purpose" : "dispute_evidence",
"size" : 28461,
"type" : "jpg"
}
Retrieve an existing file upload object.
Successful request returns a file upload object.
DEFINITION
GET https://uploads.securionpay.com/files/{FILE_UPLOAD_ID}
EXAMPLE REQUEST
curl https://uploads.securionpay.com/files/file_2nayTQXBBjaVEPVtCwGCbqOj
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
"created" : 1415810511,
"objectType" : "file_upload",
"purpose" : "dispute_evidence",
"size" : 28461,
"type" : "jpg"
}
List file upload objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns list of a file upload object.
DEFINITION
GET https://uploads.securionpay.com/files
EXAMPLE REQUEST
curl https://uploads.securionpay.com/files?limit=2
EXAMPLE RESPONSE
{
"hasMore": false,
"list": [{
"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
"created" : 1415810511,
"objectType" : "file_upload",
"purpose" : "dispute_evidence",
"size" : 28461,
"type" : "jpg"
}]
}
Fraud Warning represents information received from card issuer regarding charge.
EXAMPLE OBJECT
{
"id" : "fw_O7FRMgfC5g9BFqjEFepcB07J",
"created" : 1609325894,
"objectType" : "fraud_warning",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"actionable" : true
}
Retrieve an existing fraud warning object.
Successful request returns a fraud warning object.
DEFINITION
GET https://api.securionpay.com/fraud-warnings/{FRAUD_WARNING_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/fraud-warnings/fw_O7FRMgfC5g9BFqjEFepcB07J \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "fw_O7FRMgfC5g9BFqjEFepcB07J",
"created" : 1609325894,
"objectType" : "fraud_warning",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"actionable" : true
}
List fraud warning objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of fraud-warning objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/fraud-warnings
EXAMPLE REQUEST
curl "https://api.securionpay.com/fraud-warnings" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "fw_O7FRMgfC5g9BFqjEFepcB07J",
"created" : 1609325894,
"objectType" : "fraud_warning",
"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
"actionable" : true
},
{ ... },
{ ... }
],
"hasMore" : true
}
Payout represents details of funds received from acquirer. They are made on varying schedules, depending on your acquirer.
EXAMPLE OBJECT
{
"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1413561422,
"objectType" : "payout",
"periodEnd" : 1413325441,
"periodStart" : 1413012367,
"amount" : 499,
"currency" : "EUR"
}
Retrieve an existing payout object.
Successful request returns a payout object.
DEFINITION
GET https://api.securionpay.com/payouts/{PAYOUT_ID}
EXAMPLE REQUEST
curl https://api.securionpay.com/payout/po_bLu3vzO8yhAFhbxFEadm6HUV \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1413561422,
"objectType" : "payout",
"periodEnd" : 1413325441,
"periodStart" : 1413012367,
"amount" : 499,
"currency" : "EUR"
}
List payout objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of payout objects.
Results are sorted by payout date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/payouts
EXAMPLE REQUEST
curl "https://api.securionpay.com/payouts?limit=3" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1413561422,
"objectType" : "payout",
"periodEnd" : 1413325441,
"periodStart" : 1413012367,
"amount" : 499,
"currency" : "EUR"
},
{ ... },
{ ... }
],
"hasMore" : true
}
charge
, refund
, credit
, chargeback
, chargeback_represented
, reserve_withhold
, reserve_release
, acquirer_fee
or adjustment
.
EXAMPLE OBJECT
{
"id" : "pot_Y8x0X5d5zoRj6uI26vibFwkz",
"created" : 1604620800,
"objectType" : "payout_transaction",
"type" : "charge",
"amount" : 413,
"currency" : "EUR",
"fee" : 39,
"source" : "char_1jmzPboimq0IDwz8zLXdX9qw",
"payout" : "po_gb48tN1UdWznKQHexcAAlbkK"
}
List payout transaction objects.
created
attribute.
Can have following attributes:
gt
- return objects created after given timestampgte
- return objects created after or exactly on given timestamplt
- return objects created before given timestamplte
- return objects created before or exactly on given timestampid=some-example-id
- then you can make another request with startingAfterId=some-example-id
to get next page of that list.
id=some-example-id
- then you can make another request with endingBeforeId=some-example-id
to get previous page of that list.
Successful request returns a list of payout transaction objects.
Results are sorted by creation date, with most recent objects first.
DEFINITION
GET https://api.securionpay.com/payout-transactions
EXAMPLE REQUEST
curl "https://api.securionpay.com/payout-transactions?payout=po_gb48tN1UdWznKQHexcAAlbkK" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"list" : [
{
"id" : "pot_Y8x0X5d5zoRj6uI26vibFwkz",
"created" : 1604620800,
"objectType" : "payout_transaction",
"type" : "charge",
"amount" : 413,
"currency" : "EUR",
"fee" : 39,
"source" : "char_1jmzPboimq0IDwz8zLXdX9qw",
"payout" : "po_gb48tN1UdWznKQHexcAAlbkK"
},
{ ... },
{ ... }
],
"hasMore" : true
}
Creates test Payout based on test mode charges, refunds, chargebacks and credits.
Successful request returns payout object.
DEFINITION
POST https://api.securionpay.com/payouts
EXAMPLE REQUEST
curl -X POST "https://api.securionpay.com/payouts" \
-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
EXAMPLE RESPONSE
{
"id" : "po_bLu3vzO8yhAFhbxFEadm6HUV",
"created" : 1413561422,
"objectType" : "payout",
"periodEnd" : 1413325441,
"periodStart" : 1413012367,
"amount" : 499,
"currency" : "EUR"
}