SecurionPay

Introduction

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.

https://api.securionpay.com/
				

Authentication

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 you 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.

curl https://api.securionpay.com/charges \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

Errors

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.

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
				

Error object

Attributes

type

string Type of error. Possible values are:
invalid_request - Request has invalid or missing parameters
card_error - Card processing has failed
gateway_error - Something went wrong on our side
rate_limit_error - Requests hit the API too quickly

code

string Additional details about card error (only present when type=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.

message

string A human-readable message that describes reason of this error. Note that content of this message is not intended to be parsed and format of this message can change at any moment.

chargeId

string Identifier of charge object associated with this error. Only present when request resulted in declined charge.

blacklistRuleId

string Identifier of blacklist rule object that matched this request. Only present when request was blocked by blacklist.

creditId

string Identifier of credit object associated with this error. Only present when request resulted in declined credit.

{
	"error" : {
		"type" : "card_error",
		"code" : "invalid_number",
		"message" : "The card number is not a valid card number."
	}
}
				

Metadata

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.

{
	"email" : "[email protected]",
	"metadata" : {
		"key1" : "value1",
		"key2" : "value2"
	}
}
				

{
	"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"created" : 1415810511,
	"objectType" : "customer",
	"email" : "[email protected]",
	"metadata" : {
		"key1" : "value1",
		"key2" : "value2"
	}
}
				

Charges

Change represents payment made with a credit or a debit card.

Charge object

Attributes

id

string

created

timestamp

objectType

string (value is always "charge")

amount

integer Charge amount in minor units of given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".

currency

string Charge currency represented as three-letter ISO currency code.

description

string

card

card object Card that was used to create this charge.

customerId

string Identifier of customer who is owner of this charge or null if this charge is not associated with any customer.

subscriptionId

string Identifier of subscription associated with this charge or null if this charge is not associated with any subscription.

captured

boolean

refunded

boolean

refunds

list of refund objects List of refunds that was done on this charge.

disputed

boolean

dispute

dispute object Details about dispute related to this charge.

fraudDetails

object Details about fraud check done on this charge. Can contain following attributes:

• status (string) - can be one of following: safe, suspicious or fraudulent
• score (integer) - percentage chance that the charge is a fraud

fromCrossSale

object This attribute is present when this charge was created from cross-sale offer. Can contain following attributes:

• offerId (string) - Identifier of cross-sale offer that was used to create this charge
• partnerId (string) - Identifier of partner who added your cross-sale offer to his checkout (this attribute is not present if that was your checkout).

withCrossSales

list of objects List of successful cross-sales that were created after this charge. Each object in list can contain following attributes:

• offerId (string) - Identifier of cross-sale offer that was used to create this cross-sale
• partnerId (string) - Identifier of partner who is owner of cross-sale offer that was used to create this cross-sale. (this attribute is not present if that was your cross-sale offer).
• chargeId (string) - Identifier of charge that was create by this cross-sale (NOTE: if that charge is owned by your partner then you will not be able retrieve details of that charge)
• amount (integer) - Cross-sale charge amount (in minor units).
• currency (string) - Cross-sale charge currency (represented as three-letter ISO currency code).

shipping

object Shipping details. Can contain following attributes:

• name (string) - name of the recipient
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code

billing

object Billing details. Can contain following attributes:

• name (string) - name of billed person or company
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code
• vat (string) - tax identification number

threeDSecureInfo

object Additional data present if card used to create this charge was verified with 3D Secure. Can contain following attributes:

• amount (integer) - amount in minor units that was used in 3D Secure
• currency (string) - currency that was used in 3D Secure (represented as three-letter ISO currency code)
• enrolled (boolean) - whatever card used to create this charge supports 3D Secure
• liabilityShift (string) - can have one of following values:
  successful - 3D Secure was completed successfully
  failed - 3D Secure is supported, but was not completed successfully
  not_possible - 3D Secure is not supported

metadata

metadata object

failureCode

string Error code that describes why charge has failed. Only present in failed charges. For list of possible values see code attribute in error object.

failureMessage

string Human-readable message that describes why charge has failed. Only present in failed charges.

{
	"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",
	  "country" : "CH"
	},
	"customerId" : null,
	"captured" : true,
	"refunded" : false,
	"refunds" : [],
	"disputed" : false,
	"metadata" : {}
}
				

Create a new Charge

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.

Arguments

amount

integer, required Charge amount in minor units of given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".

currency

string, required Charge currency represented as three-letter ISO currency code.

description

string, optional

customerId

string, optional (either customerId or card is required) Identifier of customer that will be associated with this charge. This field is required if charge is being created with customer's existing card. If specified then successful charge created with new card will add that card to customer's cards and it will be set as customer's default card.

card

card token, card details or card identifier, optional (either customerId or card is required) Can be one of following:

• card token (for example obtained from custom form)
• card details (same as in card create request)
• card identifier (must be an existing card that is associated with customer specified in customerId field)

If card is not provided then customer's default card will be used.

captured

boolean, optional (default is true) Whether this charge should be immediately captured. When set to false charge is only authorized (or pre-authorized) and needs to be captured later.

shipping

object, optional Shipping details. Can contain following attributes:

• name (string) - name of the recipient
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code

billing

object, optional Billing details. Can contain following attributes:

• name (string) - name of billed person or company
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code
• vat (string) - tax identification number

threeDSecure

object, optional 3D Secure options. Can contain following attributes:

• requireAttempt (boolean, default is false) - the charge will fail when 3D Secure verification was not attempted
• requireEnrolledCard (boolean, default is false) - the charge will fail if card doesn't support 3D Secure (is not enrolled for 3D Secure verification)
• requireSuccessfulLiabilityShiftForEnrolledCard (boolean, default is true) - the charge will fail when card supports 3D Secure verification, but that verification was not successful (i.e. customer cancelled the verification or provided invalid information is 3D Secure popup)

metadata

metadata object, optional

Result

Successful request returns a charge object that represents created charge.

POST https://api.securionpay.com/charges
				

curl https://api.securionpay.com/charges \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "amount=499" \
	-d "currency=EUR" \
	-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe" \
	-d "description=Example charge"
				

{
	"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",
	  "country" : "CH"
	},
	"captured" : true,
	"refunded" : false,
	"disputed" : false
}
				

Retrieve an existing Charge

Retrieve an existing charge object.

Arguments

chargeId

string, required Identifier of charge object that should be retrieved.

Result

Successful request returns a charge object.

GET https://api.securionpay.com/charges/{CHARGE_ID}
				

curl https://api.securionpay.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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",
	  "country" : "CH"
	},
	"captured" : true,
	"refunded" : false,
	"disputed" : false
}
				

Update an existing Charge

Update an existing charge object.

Any not provided parameter will be left unchanged.

Arguments

chargeId

string, required Identifier of charge object that should be updated.

customerId

string, optional Identifier of customer that will be associated with this charge. Updating this field is only possible for charge that is not assigned to any customer. Assigning successful charge to customer will add card that was used to create that charge to customer's cards and is will be set as customer's default card.

description

string, optional

shipping

object, optional Shipping details. Can contain following attributes:

• name (string) - name of the recipient
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code

billing

object, optional Billing details. Can contain following attributes:

• name (string) - name of billed person or company
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code
• vat (string) - tax identification number

metadata

metadata object, optional

Result

Successful request returns a charge object that was updated.

POST https://api.securionpay.com/charges/{CHARGE_ID}
				

curl https://api.securionpay.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "description=New description"
				

{
	"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",
	  "country" : "CH"
	},
	"captured" : true,
	"refunded" : false,
	"disputed" : false
}
				

Capture a Charge

Capture a existing charge that was created with captured=false attribute. This is second part of two step payment flow.

Arguments

chargeId

string, required Identifier of charge object that should be captured.

Result

Successful request returns a charge object that was captured.

POST https://api.securionpay.com/charges/{CHARGE_ID}/capture
				

curl https://api.securionpay.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q/capture \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X POST
				

{
	"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",
	  "country" : "CH"
	},
	"captured" : true,
	"refunded" : false,
	"disputed" : false
}
				

Refund a Charge

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.

Arguments

chargeId

string, required Identifier of charge object that should be captured.

amount

integer, optional (default is current amount of charge) The amount (in minor units) to refund. This must be less or equal to current amount of charge that is being refunded.

Result

Successful request returns a charge object that was refunded.

POST https://api.securionpay.com/charges/{CHARGE_ID}/refund
				

curl https://api.securionpay.com/charges/char_ORVCrwOrTkGsDwM3H50OIW7Q/refund \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "amount=499"
				

{
	"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",
	  "country" : "CH"
	},
	"captured" : true,
	"refunded" : true,
	"refunds" : [
		{
			"created" : 1415967655,
			"amount" : 499,
			"currency" : "EUR"
		},
	],
	"disputed" : false
}
				

List Charges

List charge objects.

Arguments

created

object, optional Filter results based on value of created attribute. Can have following attributes:

• gt - return objects created after given timestamp
• gte - return objects created after or exactly on given timestamp
• lt - return objects created before given timestamp
• lte - return objects created before or exactly on given timestamp

customerId

string, optional Returns only charges associated with given customer.

limit

integer, optional (default is 10) Limit the number of returned objects. Limit must be between 1 and 100.

startingAfterId

string, optional Cursor used for pagination (getting next page). For example, if you make a list request and receive 10 objects, where last object have id=some-example-id - then you can make another request with startingAfterId=some-example-id to get next page of that list.

endingBeforeId

string, optional Cursor used for pagination (getting previous page). For example, if you make a list request and receive 10 objects, where first object have id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get previous page of that list.

Result

Successful request returns a list of charge objects.

Results are sorted by creation date, with most recent objects first.

GET https://api.securionpay.com/charges
				

curl "https://api.securionpay.com/charges?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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",
			  "country" : "CH"
			},
			"captured" : true,
			"refunded" : false,
			"disputed" : false
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}
				

Dispute object

Attributes

objectType

string (value is always "dispute")

created

timestamp

updated

timestamp

amount

integer Dispute amount in minor units of given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".

currency

string Dispute currency represented as three-letter ISO currency code.

status

string Can have one of following values:

• RETRIEVAL_REQUEST_NEW
• RETRIEVAL_REQUEST_REPRESENTED
• CHARGEBACK_NEW
• CHARGEBACK_REPRESENTED_SUCCESSFULLY
• CHARGEBACK_REPRESENTED_UNSUCCESSFULLY

reason

string Can have one of following values:

• FRAUDULENT
• UNRECOGNIZED
• DUPLICATE
• SUBSCRIPTION_CANCELED
• PRODUCT_NOT_RECEIVED
• PRODUCT_UNACCEPTABLE
• CREDIT_NOT_PROCESSED
• GENERAL

acceptedAsLost

boolean

{
	"objectType" : "dispute",
	"created" : 1415896911,
	"updated" : 1415896911,
	"status" : "CHARGEBACK_NEW",
	"reason" : "GENERAL",
	"amount" : 499,
	"currency" : "EUR",
	"acceptedAsLost" : false
}
				

Customers

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.

Customer object

Attributes

id

string

created

timestamp

objectType

string (value is always "customer")

email

string

description

string

defaultCardId

string Identifier of customer's default card.

cards

list of card object List of cards associated with this customer.

metadata

metadata 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",
      "country" : "CH"
    }
  ],
  "metadata" : { }
}

Create a Customer

Creates a new customer object.

Arguments

email

string, required

description

string, optional

card

charge identifier, card token or card details, optional If provided then customer will be created with this card and it will be set as default. Can be one of following:

• card token (for example obtained from custom form)
• charge identifier - will save card that was used to create charge (only possible for successful charge that is not assigned to any customer and will result in that charge being assigned to this customer)
• card details (same as in card create request)

metadata

metadata object, optional

Result

Successful request returns a customer object that represents created customer.

POST https://api.securionpay.com/customers
				

curl https://api.securionpay.com/customers \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "[email protected]" \
	-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe"
				

{
  "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",
      "country" : "CH"
    }
  ]
}

Retrieve an existing Customer

Retrieve an existing customer object.

Arguments

customerId

string, required Identifier of customer object that should be retrieved.

Result

Successful request returns a customer object.

GET https://api.securionpay.com/customers/{CUSTOMER_ID}
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
  "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",
      "country" : "CH"
    }
  ]
}

Update an existing Customer

Update an existing customer object.

Any not provided parameter will be left unchanged.

Arguments

customerId

string, required Identifier of customer object that should be updated.

email

string, optional

description

string, optional

defaultCardId

string, optional Identifier of customer's card that will be set as default card.

card

charge identifier, card token or card details, optional If provided then new card will be added to customer's cards and it will be set as default. Can be one of following:

• card token (for example obtained from custom form)
• charge identifier - will save card that was used to create charge (only possible for successful charge that is not assigned to any customer and will result in that charge being assigned to this customer)
• card details (same as in card create request)

metadata

metadata object, optional

Result

Successful request returns a customer object that was updated.

POST https://api.securionpay.com/customers/{CUSTOMER_ID}
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "[email protected]" \
	-d "description=New description"
				

{
  "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",
      "country" : "CH"
    }
  ]
}

Delete a Customer

Deletes an existing customer object.

Arguments

customerId

string, required Identifier of customer object that should be deleted.

Result

Successful request returns identifier of deleted customer object.

DELETE https://api.securionpay.com/customers/{CUSTOMER_ID}
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE
				

{
	"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
}
				

List Customers

List customer objects.

Arguments

created

object, optional Filter results based on value of created attribute. Can have following attributes:

• gt - return objects created after given timestamp
• gte - return objects created after or exactly on given timestamp
• lt - return objects created before given timestamp
• lte - return objects created before or exactly on given timestamp

deleted

boolean, optional (default is false) Can be used to list deleted customers.

email

string, optional Returns only customers with given email.

limit

integer, optional (default is 10) Limit the number of returned objects. Limit must be between 1 and 100.

startingAfterId

string, optional Cursor used for pagination (getting next page). For example, if you make a list request and receive 10 objects, where last object have id=some-example-id - then you can make another request with startingAfterId=some-example-id to get next page of that list.

endingBeforeId

string, optional Cursor used for pagination (getting previous page). For example, if you make a list request and receive 10 objects, where first object have id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get previous page of that list.

Result

Successful request returns a list of customer objects.

Results are sorted by creation date, with most recent objects first.

GET https://api.securionpay.com/customers
				

curl "https://api.securionpay.com/customers?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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",
		      "country" : "CH"
		    }
		  ]
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

Cards

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).

Card object

Attributes

id

string

created

timestamp

objectType

string (value is always "card")

first6

integer

last4

integer

fingerprint

string Unique identifier of card number. Can be used to check if two different charges were done using the same card number.

expMonth

integer

expYear

integer

cardholderName

string

customerId

string Identifier of customer that is owner of this card.

brand

string Brand of card. Possible values are: Visa, American Express, MasterCard, Maestro, Discover, JCB, Diners Club, Unknown

type

string Type of card. Possible values are: Credit Card, Debit Card, Unknown

country

string, Country of card's Issuing Bank (represented as two-letter ISO country code). This value is derived from card's Bank Identification Number (BIN).

addressLine1

string

addressLine2

string

addressCity

string

addressState

string

addressZip

string

addressCountry

string Country represented as three-letter ISO country code.

fraudCheckData

object Additional data used for fraud protection. Can contain following attributes:

• ipAddress (string) - IP address of the user
• ipCountry (string) - country derived from user's IP address (represented as two-letter ISO country code)
• email (string) - e-mail address of the user
• userAgent (string) - value of "User-Agent" HTTP header that was sent by the user
• acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user

{
  "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",
  "country" : "CH",
  "addressLine1" : null,
  "addressLine2" : null,
  "addressCity" : null,
  "addressState" : null,
  "addressZip" : null,
  "addressCountry" : null
}

Create a new Card

Creates a new card object.

There are three ways to create a new card object:

• use card token (for example obtained from custom form)
• use charge identifier - will save card that was used to create charge (only possible for successful charge that is not assigned to any customer and will result in that charge being assigned to this customer)
• specify all card details (as seen in arguments list below)

Arguments

number

string, required Card number without any separators.

expMonth

string, required Card expiration month.

expYear

string, required Card expiration year.

cvc

string, required Card security code.

cardholderName

string, optional

addressLine1

string, optional

addressLine2

string, optional

addressCity

string, optional

addressState

string, optional

addressZip

string, optional

addressCountry

string, optional Country represented as three-letter ISO country code.

fraudCheckData

object, optional Additional data used for fraud protection. Can contain following attributes:

• ipAddress (string) - IP address of the user
• email (string) - e-mail address of the user
• userAgent (string) - value of "User-Agent" HTTP header that was sent by the user
• acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user

Result

Successful request returns a card object that represents created card.

POST https://api.securionpay.com/customers/{CUSTOMER_ID}/cards
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "id=tok_NGsyDoJQXop5Pqqi6HizbJTe"
				

{
  "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",
  "country" : "CH"
}

Retrieve an existing Card

Retrieve an existing card object.

Arguments

customerId

string, required Identifier of customer object that is owner of card object that should be retrieved.

cardId

string, required Identifier of card object that should be retrieved.

Result

Successful request returns a card object.

GET https://api.securionpay.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
  "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",
  "country" : "CH"
}

Update an existing Card

Update an existing card object.

Any not provided parameter will be left unchanged.

Arguments

customerId

string, required Identifier of customer object that is owner of card object that should be updated.

cardId

string, required Identifier of card object that should be updated.

expMonth

string, optional Card expiration month.

expYear

string, optional Card expiration year.

cardholderName

string, optional

addressCountry

string, optional Country represented as three-letter ISO country code.

addressCity

string, optional

addressState

string, optional

addressZip

string, optional

addressLine1

string, optional

addressLine2

string, optional

Result

Successful request returns a card object that was updated.

POST https://api.securionpay.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "cardholderName=Jane Doe"
				

{
  "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",
  "country" : "CH"
}

Delete a Card

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.

Arguments

customerId

string, required Identifier of customer object that is owner of card object that should be deleted.

cardId

string, required Identifier of card object that should be deleted.

Result

Successful request returns identifier of deleted card object.

DELETE https://api.securionpay.com/customers/{CUSTOMER_ID}/cards/{CARD_ID}
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards/card_8P7OWXA5xiTS1ISnyZcum1KV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE
				

{
	"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
}
				

List Cards

List card objects for given customer.

Arguments

customerId

string, required Identifier of customer object whose cards should be listed.

created

object, optional Filter results based on value of created attribute. Can have following attributes:

• gt - return objects created after given timestamp
• gte - return objects created after or exactly on given timestamp
• lt - return objects created before given timestamp
• lte - return objects created before or exactly on given timestamp

deleted

boolean, optional (default is false) Can be used to list deleted cards.

limit

integer, optional (default is 10) Limit the number of returned objects. Limit must be between 1 and 100.

startingAfterId

string, optional Cursor used for pagination (getting next page). For example, if you make a list request and receive 10 objects, where last object have id=some-example-id - then you can make another request with startingAfterId=some-example-id to get next page of that list.

endingBeforeId

string, optional Cursor used for pagination (getting previous page). For example, if you make a list request and receive 10 objects, where first object have id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get previous page of that list.

Result

Successful request returns a list of card objects.

Results are sorted by creation date, with most recent objects first.

GET https://api.securionpay.com/customers/{CUSTOMER_ID}/cards
				

curl "https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/cards?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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",
		  "country" : "CH"
		},
		{ ... },
		{ ... }
	],
	"hasMore" : false
}

Subscriptions

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.

Subscription object

Attributes

id

string

created

timestamp

objectType

string (value is always "subscription")

planId

string Identifier of a plan assigned to this subscription.

customerId

string Identifier of a customer who is owner of this subscription.

quantity

integer Multiplier that will be applied to change amount defined in a plan. For example a plan with amount=100 used in subscription with quantity=5 will result in changes with amount=500.

captureCharges

boolean Whatever charges created by this subscription will be immediately captured (see captured attribute in charge request). If set to false then you need to manually capture each charge created by this subscription.

status

string Status of this subscription. Possible values are:

• trialing - subscription was created from plan with trial days and is still in trial period
• active - subscription is active and will be renewed after end of current billing cycle
• past_due - renewing of subscription has failed
• canceled - subscription was manually canceled or all retry renew attempts has failed
• unpaid - all retry renew attempts has failed

Note that resulting status when all renew retry attempts has failed depends on your your account settings.

remainingBillingCycles

integer Defines how many billing cycles remains before this subscription will be automatically canceled.

start

timestamp Date the subscription started using current plan.
Will have different value then created if subscription plan was changed.

currentPeriodStart

timestamp Start of current billing period.
For active subscription this should match time of last rebill, but can be different if there was problem creating rebill charge (for example because of declined chage).

currentPeriodEnd

timestamp End of current billing period.
For active subscription this is the time when next rebill will be attempted.

canceledAt

timestamp The date when subscription was requested to be canceled.

endedAt

timestamp The date when subscription was canceled.
Will have different value then canceledAt if subscription was canceled with atPeriodEnd=true.

trialStart

timestamp Start of trial period.

trialEnd

timestamp End of trial period.

cancelAtPeriodEnd

boolean If set to true then subscription will be canceled at end of current billing period.

shipping

object Shipping details. Can contain following attributes:

• name (string) - name of the recipient
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code

billing

object Billing details. Can contain following attributes:

• name (string) - name of billed person or company
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code
• vat (string) - tax identification number

metadata

metadata 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" : {}
}
				

Create a new Subscription

Creates a new subscription object.

Arguments

customerId

string Identifier of a customer who will be owner of this subscription.

planId

string Identifier of a plan that will be assigned to this subscription.

card

charge identifier, card token or card details, optional If provided then new card will be added to customer's cards and it will be set as default. Can be one of following:

• card token (for example obtained from custom form)
• charge identifier - will save card that was used to create charge (only possible for successful charge that is not assigned to any customer and will result in that charge being assigned to this customer)
• card details (same as in card create request)

quantity

integer, optional (default is 1)

captureCharges

boolean, optional (default is true) Whatever charges created by this subscription will be immediately captured (see captured attribute in charge request). If set to false then you need to manually capture each charge created by this subscription.

trialEnd

timestamp, optional Defines the end of trial period for this subscription. If provided then it will override trial setting defined in plan.

shipping

object, optional Shipping details. Can contain following attributes:

• name (string) - name of the recipient
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code

billing

object, optional Billing details. Can contain following attributes:

• name (string) - name of billed person or company
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code
• vat (string) - tax identification number

metadata

metadata object, optional

Result

Successful request returns a subscription object that represents created subscription.

POST https://api.securionpay.com/customers/{CUSTOMER_ID}/subscriptions
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/subscriptions \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "planId=plan_bLu3vzO8yhAFhbxFEadm6HUV"
				

{
	"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

Retrieve an existing subscription object.

Arguments

customerId

string, required Identifier of customer object that is owner of subscription object that should be retrieved.

subscriptionId

string, required Identifier of subscription object that should be retrieved.

Result

Successful request returns a subscription object.

GET https://api.securionpay.com/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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

Update an existing subscription object.

Any not provided parameter will be left unchanged.

Arguments

customerId

string, required Identifier of customer object that is owner of subscription object that should be updated.

subscriptionId

string, required Identifier of subscription object that should be updated.

planId

string, optional Identifier of a plan that will be assigned to this subscription.

card

charge identifier, card token or card details, optional If provided then new card will be added to customer's cards and it will be set as default. Can be one of following:

• card token (for example obtained from custom form)
• charge identifier - will save card that was used to create charge (only possible for successful charge that is not assigned to any customer and will result in that charge being assigned to this customer)
• card details (same as in card create request)

quantity

integer, optional

captureCharges

boolean, optional Whatever charges created by this subscription will be immediately captured (see captured attribute in charge request). If set to false then you need to manually capture each charge created by this subscription.

trialEnd

timestamp, optional Defines the end of trial period for this subscription. Special value of -1 can be used to end trial immediately.

shipping

object, optional Shipping details. Can contain following attributes:

• name (string) - name of the recipient
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code

billing

object, optional Billing details. Can contain following attributes:

• name (string) - name of billed person or company
• address (object) - address object, can contain following attributes:
  • line1 (string) - address first line
  • line2 (string) - address second line
  • zip (string) - ZIP (postal) code
  • city (string) - city or town
  • state (string) - state or province
  • country (string) - country represented as two-letter ISO country code
• vat (string) - tax identification number

metadata

metadata object, optional

Result

Successful request returns a subscription object that was updated.

POST https://api.securionpay.com/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "quantity=5"
				

{
	"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
}
				

Cancel a Subscription

Cancels an existing subscription.

Arguments

customerId

string, required Identifier of customer object that is owner of subscription object that should be canceled.

subscriptionId

string, required Identifier of subscription object that should be canceled.

atPeriodEnd

boolean, optional (default is false) Whatever or not delay cancellation of subscription until the end of the current period. By default subscription is canceled immediately.

Result

Successful request returns a subscription object that was canceled.

DELETE https://api.securionpay.com/customers/{CUSTOMER_ID}/subscriptions/{SUBSCRIPTION_ID}
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5 \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE
				

curl https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/subscriptions/sub_vrEaVmRDW0oKz8ycyy8Yc4l5?atPeriodEnd=true \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE
				

{
	"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 Subscriptions

List subscription objects.

Arguments

customerId

string, required Identifier of customer object whose subscriptions should be listed.

created

object, optional Filter results based on value of created attribute. Can have following attributes:

• gt - return objects created after given timestamp
• gte - return objects created after or exactly on given timestamp
• lt - return objects created before given timestamp
• lte - return objects created before or exactly on given timestamp

deleted

boolean, optional (default is false) Can be used to list deleted (canceled or unpaid) subscriptions.

limit

integer, optional (default is 10) Limit the number of returned objects. Limit must be between 1 and 100.

startingAfterId

string, optional Cursor used for pagination (getting next page). For example, if you make a list request and receive 10 objects, where last object have id=some-example-id - then you can make another request with startingAfterId=some-example-id to get next page of that list.

endingBeforeId

string, optional Cursor used for pagination (getting previous page). For example, if you make a list request and receive 10 objects, where first object have id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get previous page of that list.

Result

Successful request returns a list of subscription objects.

Results are sorted by creation date, with most recent objects first.

GET https://api.securionpay.com/customers/{CUSTOMER_ID}/subscriptions
				

curl "https://api.securionpay.com/customers/cust_AoR0wvgntQWRUYMdZNLYMz5R/subscriptions?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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
}
				

Plans

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.

Plan object

Attributes

id

string

created

timestamp

objectType

string (value is always "plan")

amount

integer Subscription charge amount in minor units of given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".

currency

string Subscription charge currency represented as three-letter ISO currency code.

interval

string Frequency of subscription charges. Possible values are: hour, day, week, month, year

intervalCount

integer Number of intervals between subscription charges. For example interval=day and intervalCount=10 will result in charge every 10 days.

billingCycles

integer Number of charges after which subscription will be automatically canceled. Value of null means no limit on number of charges.

name

string Display name of this plan

trialPeriodDays

integer Number of days between creation of subscription and the first charge.

recursTo

plan identifier When subscription is automatically canceled (due to reaching limit of billingCycles) it will move to plan defined by this attribute.

metadata

metadata 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" : {}
}
				

Create a Plan

Creates a new plan object.

Arguments

amount

integer, required Subscription charge amount in minor units of given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".

currency

string, required Subscription charge currency represented as three-letter ISO currency code.

interval

string, required Frequency of subscription charges. Possible values are: hour, day, week, month, year

name

string, required Display name of this plan

intervalCount

integer, optional (default is 1) Number of intervals between subscription charges. For example interval=day and intervalCount=10 will result in charge every 10 days.

billingCycles

integer, optional Number of charges after which subscription will be automatically canceled. Value of null means no limit on number of charges.

trialPeriodDays

integer, optional (default is 0) Number of days between creation of subscription and first charge.

recursTo

plan identifier, optional When subscription is automatically canceled (due to reaching limit of billingCycles) it will move to plan defined by this attribute.

metadata

metadata object, optional

Result

Successful request returns a plan object that represents created plan.

POST https://api.securionpay.com/plans
				

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"
				

{
	"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"created" : 1415973454,
	"objectType" : "plan",
	"amount" : 499,
	"currency" : "EUR",
	"interval" : "day",
	"intervalCount" : 10,
	"name" : "Example plan",
	"trialPeriodDays" : 0
}
				

Retrieve an existing Plan

Retrieve an existing plan object.

Arguments

planId

string, required Identifier of plan object that should be retrieved.

Result

Successful request returns a plan object.

GET https://api.securionpay.com/plans/{PLAN_ID}
				

curl https://api.securionpay.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"created" : 1415973454,
	"objectType" : "plan",
	"amount" : 499,
	"currency" : "EUR",
	"interval" : "day",
	"intervalCount" : 10,
	"name" : "Example plan",
	"trialPeriodDays" : 0
}
				

Update an existing Plan

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.

Arguments

planId

string, required Identifier of plan object that should be updated.

amount

integer, optional Subscription charge amount in minor units of given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".

currency

string, optional Subscription charge currency represented as three-letter ISO currency code.

name

string, optional Display name of this plan

metadata

metadata object, optional

Result

Successful request returns a plan object that was updated.

POST https://api.securionpay.com/plans/{PLAN_ID}
				

curl https://api.securionpay.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "name=New plan"
				

{
	"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"created" : 1415973454,
	"objectType" : "plan",
	"amount" : 499,
	"currency" : "EUR",
	"interval" : "day",
	"intervalCount" : 10,
	"name" : "New plan",
	"trialPeriodDays" : 0
}
				

Delete a Plan

Deletes an existing plan object.

Note that when you delete a plan then existing subscriptions will continue to be charged until they are canceled.

Arguments

planId

string, required Identifier of plan object that should be deleted.

Result

Successful request returns identifier of deleted plan object.

DELETE https://api.securionpay.com/plans/{PLAN_ID}
				

curl https://api.securionpay.com/plans/plan_bLu3vzO8yhAFhbxFEadm6HUV \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE
				

{
	"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
}
				

List Plans

List plan objects.

Arguments

created

object, optional Filter results based on value of created attribute. Can have following attributes:

• gt - return objects created after given timestamp
• gte - return objects created after or exactly on given timestamp
• lt - return objects created before given timestamp
• lte - return objects created before or exactly on given timestamp

deleted

boolean, optional (default is false) Can be used to list deleted plans.

limit

integer, optional (default is 10) Limit the number of returned objects. Limit must be between 1 and 100.

startingAfterId

string, optional Cursor used for pagination (getting next page). For example, if you make a list request and receive 10 objects, where last object have id=some-example-id - then you can make another request with startingAfterId=some-example-id to get next page of that list.

endingBeforeId

string, optional Cursor used for pagination (getting previous page). For example, if you make a list request and receive 10 objects, where first object have id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get previous page of that list.

Result

Successful request returns a list of plan objects.

Results are sorted by creation date, with most recent objects first.

GET https://api.securionpay.com/plans
				

curl "https://api.securionpay.com/plans?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"list" : [
		{
			"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
			"created" : 1415973454,
			"objectType" : "plan",
			"amount" : 499,
			"currency" : "EUR",
			"interval" : "day",
			"intervalCount" : 10,
			"name" : "Example plan",
			"trialPeriodDays" : 0
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}
				

Events

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.

Event object

Attributes

id

string

created

timestamp

objectType

string (value is always "event")

type

string Type of event. For more informations see list of event types.

data

object Object that is subject of this event. For example event with type=CHARGE_SUCCEEDED will have a charge object as value of this attribute.

log

string Identifier of request log associated with this event.

{
	"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",
		  "country" : "CH"
		},
		"captured" : true,
		"refunded" : false,
		"disputed" : false
	},
	"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
}
				

Retrieve an Event

Retrieve an existing event object.

Arguments

eventId

string, required Identifier of event object that should be retrieved.

Result

Successful request returns an event object.

GET https://api.securionpay.com/events/{EVENT_ID}
				

curl https://api.securionpay.com/events/event_EY7CzyQiffJykW8rC5wSRnAj \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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",
			  "country" : "CH"
			},
		"captured" : true,
		"refunded" : false,
		"disputed" : false
	},
	"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
}
				

List Events

List event objects.

Arguments

created

object, optional Filter results based on value of created attribute. Can have following attributes:

• gt - return objects created after given timestamp
• gte - return objects created after or exactly on given timestamp
• lt - return objects created before given timestamp
• lte - return objects created before or exactly on given timestamp

limit

integer, optional (default is 10) Limit the number of returned objects. Limit must be between 1 and 100.

startingAfterId

string, optional Cursor used for pagination (getting next page). For example, if you make a list request and receive 10 objects, where last object have id=some-example-id - then you can make another request with startingAfterId=some-example-id to get next page of that list.

endingBeforeId

string, optional Cursor used for pagination (getting previous page). For example, if you make a list request and receive 10 objects, where first object have id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get previous page of that list.

Result

Successful request returns a list of event objects.

Results are sorted by creation date, with most recent objects first.

GET https://api.securionpay.com/events
				

curl "https://api.securionpay.com/events?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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",
				  "country" : "CH"
				},
				"captured" : true,
				"refunded" : false,
				"disputed" : false
			},
			"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}
				

Types of Events

CHARGE_SUCCEEDED

Occurs when new charge is successfully created. Event data is a charge object.

CHARGE_FAILED

Occurs when creation of new charge fails. Event data is a charge object.

CHARGE_UPDATED

Occurs when charge object is updated. Event data is a charge object.

CHARGE_CAPTURED

Occurs when charge is captured. Event data is a charge object.

CHARGE_REFUNDED

Occurs when charge is refunded. Event data is a charge object.

CHARGE_DISPUTE_CREATED

Occurs when customer disputes charge (either chargeback or retrieval request). Event data is a charge object.

CHARGE_DISPUTE_UPDATED

Occurs when existing dispute is updated. Event data is a charge object.

CHARGE_DISPUTE_WON

Occurs when dispute is resolved as won. Event data is a charge object.

CHARGE_DISPUTE_LOST

Occurs when dispute is resolved as lost. Event data is a charge object.

CHARGE_DISPUTE_FUNDS_WITHDRAWN

Occurs when funds are removed from your account as result of dispute (chargeback). Event data is a charge object.

CHARGE_DISPUTE_FUNDS_RESTORED

Occurs when previously withdrawn funds are restored as result of winning dispute. Event data is a charge object.

CUSTOMER_CREATED

Occurs when new customer is created. Event data is a customer object.

CUSTOMER_UPDATED

Occurs when customer is updated. Event data is a customer object.

CUSTOMER_DELETED

Occurs when customer is deleted. Event data is a customer object.

CUSTOMER_CARD_CREATED

Occurs when new card is created for customer. Event data is a card object.

CUSTOMER_CARD_UPDATED

Occurs when customer's card is updated. Event data is a card object.

CUSTOMER_CARD_DELETED

Occurs when customer's card is deleted. Event data is a card object.

CUSTOMER_SUBSCRIPTION_CREATED

Occurs when new subscription is created for customer. Event data is a subscription object.

CUSTOMER_SUBSCRIPTION_UPDATED

Occurs when customer's subscription is updated. Event data is a subscription object.

CUSTOMER_SUBSCRIPTION_DELETED

Occurs when customer's subscription is cancelled. Event data is a subscription object.

PLAN_CREATED

Occurs when new plan is created. Event data is a plan object.

PLAN_UPDATED

Occurs when plan is updated. Event data is a plan object.

PLAN_DELETED

Occurs when plan is deleted. Event data is a plan object.

CROSS_SALE_OFFER_CREATED

Occurs when new cross-sale offer is created. Event data is a cross-sale offer object.

CROSS_SALE_OFFER_UPDATED

Occurs when cross-sale offer is updated. Event data is a cross-sale offer object.

CROSS_SALE_OFFER_DELETED

Occurs when cross-sale offer is deleted. Event data is a cross-sale offer object.

Tokens

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.

Token object

Attributes

id

string

created

timestamp

objectType

string (value is always "token")

first6

integer

last4

integer

fingerprint

string Unique identifier of card number. Can be used to check if two different charges were done using the same card number.

expMonth

integer

expYear

integer

brand

string Brand of card. Possible values are: Visa, American Express, MasterCard, Discover, JCB, Diners Club, Unknown

type

string Type of card. Possible values are: Credit Card, Debit Card, Unknown

cardholderName

string

addressLine1

string

addressLine2

string

addressCity

string

addressState

string

addressZip

string

addressCountry

string Country represented as three-letter ISO country code.

used

boolean

card

card object Card that was created from this token.

fraudCheckData

object Additional data used for fraud protection. Can contain following attributes:

• ipAddress (string) - IP address of the user
• ipCountry (string) - country derived from user's IP address (represented as two-letter ISO country code)
• email (string) - e-mail address of the user
• userAgent (string) - value of "User-Agent" HTTP header that was sent by the user
• acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user

threeDSecureInfo

object Additional data present if card (represented by this token) was verified with 3D Secure. Can contain following attributes:

• amount (integer) - amount in minor units that was used in 3D Secure
• currency (string) - currency that was used in 3D Secure (represented as three-letter ISO currency code)
• enrolled (boolean) - whether card represented by this token supports 3D Secure
• liabilityShift (string) - can have one of following values:
  successful - 3D Secure was completed successfully
  failed - 3D Secure is supported, but was not completed successfully
  not_possible - 3D Secure is not supported

{
  "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",
    "country" : "CH"
  }
}

Create a new Token

Creates a new token object.

This method can be called with either "API Public Key" or "API Secret Key".

Arguments

number

string, required Card number without any separators.

expMonth

string, required Card expiration month.

expYear

string, required Card expiration year.

cvc

string, required Card security code.

cardholderName

string, optional

addressLine1

string, optional

addressLine2

string, optional

addressCity

string, optional

addressState

string, optional

addressZip

string, optional

addressCountry

string, optional Country represented as three-letter ISO country code.

fraudCheckData

object, optional Additional data used for fraud protection. Can contain following attributes:

• ipAddress (string) - IP address of the user
• email (string) - e-mail address of the user
• userAgent (string) - value of "User-Agent" HTTP header that was sent by the user
• acceptLanguage (string) - value of "Accept-Language" HTTP header that was sent by the user

This attribute is only supported for requests made with "API Secret Key". For requests made with "API Public Key" value of this attribute is ignored and data is automatically collected from request.

Result

Successful request returns a token object that represents given card details.

POST https://api.securionpay.com/tokens
				

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"
				

{
  "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

Retrieve an existing token object.

Arguments

tokenId

string, required Identifier of token object that should be retrieved.

Result

Successful request returns a token object.

GET https://api.securionpay.com/tokens/{TOKEN_ID}
				

curl https://api.securionpay.com/tokens/tok_NGsyDoJQXop5Pqqi6HizbJTe \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
  "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
}

Blacklist

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.

Blacklist Rule object

Attributes

id

string

created

timestamp

objectType

string (value is always "blacklistRule")

ruleType

string, required Type of blacklist rule. Can have one of following values:

• fingerprint - will blacklist based on card's fingerprint (see fingerprint in card object)
• ip_address - will blacklist based on user's IP address (see fraudCheckData.ipAddress in card object)
• ip_country - will blacklist based on country derived from user's IP address (see fraudCheckData.ipCountry in card object)
• metadata - will blacklist based on metadata entry from charge (see metadata in charge object)
• email - will blacklist based on user's email (see email in customer object and fraudCheckData.email in card object)
• user_agent - will blacklist based on "User-Agent" HTTP header (see fraudCheckData.userAgent in card object)
• accept_language - will blacklist based on "Accept-Language" HTTP header (see fraudCheckData.acceptLanguage in card object)

fingerprint

string Used for ruleType=fingerprint.

ipAddress

string Used for ruleType=ip_address.

ipCountry

string Used for ruleType=ip_country.

metadataKey

string Used for ruleType=metadata.

metadataValue

string Used for ruleType=metadata.

email

string Used for ruleType=email.

userAgent

string Used for ruleType=user_agent.

acceptLanguage

string Used for ruleType=accept_language.

{
	"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
	"created" : 1429282784,
	"objectType" : "blacklistRule",
	"ruleType" : "fingerprint",
	"fingerprint" : "e3d8suyIDgFg3pE7"
}
				

Create a Blacklist Rule

Creates a new blacklist rule object.

Arguments

ruleType

string, required Type of blacklist rule. Can have one of following values:

• fingerprint - will blacklist based on card's fingerprint (see fingerprint in card object)
• ip_address - will blacklist based on user's IP address (see fraudCheckData.ipAddress in card object)
• ip_country - will blacklist based on country derived from user's IP address (see fraudCheckData.ipCountry in card object)
• metadata - will blacklist based on metadata entry from charge (see metadata in charge object)
• email - will blacklist based on user's email (see email in customer object and fraudCheckData.email in card object)
• user_agent - will blacklist based on "User-Agent" HTTP header (see fraudCheckData.userAgent in card object)
• accept_language - will blacklist based on "Accept-Language" HTTP header (see fraudCheckData.acceptLanguage in card object)

fingerprint

string Used for ruleType=fingerprint.

cardNumber

string Used for 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.

ipAddress

string Used for ruleType=ip_address.

ipCountry

string Used for ruleType=ip_country.

metadataKey

string Used for ruleType=metadata.

metadataValue

string Used for ruleType=metadata.

email

string Used for ruleType=email.

userAgent

string Used for ruleType=user_agent.

acceptLanguage

string Used for ruleType=accept_language.

Result

Successful request returns a blacklist rule object that represents created blacklist rule.

POST https://api.securionpay.com/blacklist
				

curl https://api.securionpay.com/blacklist \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "ruleType=fingerprint" \
	-d "fingerprint=e3d8suyIDgFg3pE7"
				

{
	"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
	"created" : 1429282784,
	"objectType" : "blacklistRule",
	"ruleType" : "fingerprint",
	"fingerprint" : "e3d8suyIDgFg3pE7"
}
				

Retrieve an existing Blacklist Rule

Retrieve an existing blacklist rule object.

Arguments

blacklistRuleId

string, required Identifier of blacklist rule object that should be retrieved.

Result

Successful request returns a blacklist Rule object.

GET https://api.securionpay.com/blacklist/{BLACKLIST_RULE_ID}
				

curl https://api.securionpay.com/blacklist/blr_O3y7VyxbszuezuDNjuBsExUf \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
	"created" : 1429282784,
	"objectType" : "blacklistRule",
	"ruleType" : "fingerprint",
	"fingerprint" : "e3d8suyIDgFg3pE7"
}
				

Delete a Blacklist Rule

Deletes an existing blacklist rule object.

Arguments

blacklistRuleId

string, required Identifier of blacklist rule object that should be deleted.

Result

Successful request returns identifier of deleted blacklist rule object.

DELETE https://api.securionpay.com/blacklist/{BLACKLIST_RULE_ID}
				

curl https://api.securionpay.com/blacklist/blr_O3y7VyxbszuezuDNjuBsExUf \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE
				

{
	"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
}
				

List Blacklist Rules

List blacklist rule objects.

Arguments

created

object, optional Filter results based on value of created attribute. Can have following attributes:

• gt - return objects created after given timestamp
• gte - return objects created after or exactly on given timestamp
• lt - return objects created before given timestamp
• lte - return objects created before or exactly on given timestamp

deleted

boolean, optional (default is false) Can be used to list deleted plans.

limit

integer, optional (default is 10) Limit the number of returned objects. Limit must be between 1 and 100.

startingAfterId

string, optional Cursor used for pagination (getting next page). For example, if you make a list request and receive 10 objects, where last object have id=some-example-id - then you can make another request with startingAfterId=some-example-id to get next page of that list.

endingBeforeId

string, optional Cursor used for pagination (getting previous page). For example, if you make a list request and receive 10 objects, where first object have id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get previous page of that list.

Result

Successful request returns a list of blacklist rule objects.

Results are sorted by creation date, with most recent objects first.

GET https://api.securionpay.com/blacklist
				

curl "https://api.securionpay.com/blacklist?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"list" : [
		{
			"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
			"created" : 1429282784,
			"objectType" : "blacklistRule",
			"ruleType" : "fingerprint",
			"fingerprint" : "e3d8suyIDgFg3pE7"
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}
				

Checkout Request

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.

Checkout Request object

Arguments

charge

object, optional (either charge, subscription or customCharge is required) Defines charge that will be created by Checkout. Can contain following attributes:

• amount (integer, required) - Charge amount in minor units of given currency
• currency (string, required) - Charge currency represented as three-letter ISO currency code
• capture (boolean, optional, default is true) - Whether this charge should be immediately captured
• metadata (metadata object, optional)

For more information about meaning of these attributes see charge create request.

subscription

object, optional (either charge, subscription or customCharge is required) Defines subscription that will be created by Checkout. Can contain following attributes:

• planId (string, required) - Identifier of a plan that will be assigned to this subscription
• captureCharges (boolean, optional, default is true) - Whatever charges created by this subscription will be immediately captured
• metadata (metadata object, optional)

For more information about meaning of these attributes see subscription create request.

customCharge

object, optional (either charge, subscription or customCharge is required) Defines charge with custom amount that will be selected by customer in Checkout. Can contain following attributes:

• amountOptions (list of integers, either amountOptions or customAmount is required) - List of predefined amounts (in minor units of given currency) that customer can choose from.
• customAmount (object, either amountOptions or customAmount is required) - Object with min and max attributes that defines valid range for custom amount that is provided by customer.
• currency (string, required) - Charge currency represented as three-letter ISO currency code
• capture (boolean, optional, default is true) - Whether this charge should be immediately captured
• metadata (metadata object, optional)

Providing 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.

customerId

string, optional Identifier of existing customer that will be used to create charge or subscription.

crossSaleOfferIds

list of strings, optional List of identifiers of cross-sale offer objects. Defines list of optional cross-sale offers that will be displayed after successful transaction in Checkout.

rememberMe

boolean, optional, default is false Whatever "remember-me" should be preselected in Checkout.

termsAndConditionsUrl

string, optional URL to your terms and conditions page. If provided then additional page will be shown in Checkout before payment page. On that page customer will have to accept your terms and conditions. Additionally if Checkout Request creates subscription then information about recurring payment is also shown on that page.

threeDSecure

object, optional 3D Secure options. Can contain following attributes:

• enable (boolean, default is false) - whether 3D secure verification should be attempted
• requireEnrolledCard (boolean, default is false) - the charge will fail if card doesn't support 3D Secure (is not enrolled for 3D Secure verification)
• requireSuccessfulLiabilityShiftForEnrolledCard (boolean, default is true) - the charge will fail when card supports 3D Secure verification, but that verification was not successful (i.e. customer cancelled the verification or provided invalid information in 3D Secure popup)

{
	"charge" : {
		"amount" : 499,
		"currency" : "EUR"
	},
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"rememberMe" : true
}
				

{
	"subscription" : {
		"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV"
	},
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"rememberMe" : true
}
				

{
	"customCharge" : {
		"amountOptions" : [100, 200, 500, 1000, 2000],
		"customAmount" : {
			"min" : 100,
			"max" : 5000
		},
		"currency":"EUR"
	},
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"rememberMe" : true
}
				

Signing a Checkout Request

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 )

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
				

Y2Y5Y2UyZDgzMzFjNTMxZjgzODlhNjE2YTE4Zjk1NzhjMTM0Yjc4NGRhYjVjYjdlNGI1OTY0ZTc3OTBmMTczY3x7ImNoYXJnZSI6eyJhbW91bnQiOjQ5OSwiY3VycmVuY3kiOiJFVVIifX0=
				

Cross-Sale Offers

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 charge will have additional fromCrossSale attribute filled with reference to that cross-sale offer
• main charge created in Checkout will have additional withCrossSale attribute filled with reference to that cross-sale charge

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.

Cross-Sale Offer object

Attributes

id

string

created

timestamp

objectType

string (value is always "crossSaleOffer")

charge

object (either charge or subscription is present) Defines charge that will be created when this cross-sale offer is bought. Can contain following attributes:

• amount (integer, required) - Charge amount in minor units of given currency
• currency (string, required) - Charge currency represented as three-letter ISO currency code
• capture (boolean, optional, default is true) - Whether this charge should be immediately captured

For more information about meaning of these attributes see charge create request.

subscription

object (either charge or subscription is present) Defines subscription that will be created when this cross-sale offer is bought. Can contain following attributes:

• planId (string, required) - Identifier of a plan that will be assigned to this subscription
• captureCharges (boolean, optional, default is true) - Whatever charges created by this subscription will be immediately captured

For more information about meaning of these attributes see subscription create request.

template

string Name of template that will be used to display this offer in Checkout. Possible values are: image_and_text, text_only.

title

string Title that will be displayed when this offer is shown in Checkout.

description

string Description that will be displayed when this offer is shown in Checkout.

imageUrl

string URL that can be used to download current image associated with this offer. This image will be displayed when this offer is shown in Checkout.

companyName

string Name of your company that will be displayed when this offer is shown in Checkout.

companyLocation

string Two letter ISO country code that defines location of your company. This location will be displayed when this offer is shown in Checkout.

termsAndConditionsUrl

string URL to your terms and conditions page. This URL will be used when this offer is shown in Checkout.

partnerId

string Identifier of partner that is owner of this offer (only present for offers not owned by you).

visibleForAllPartners

boolean Whether this offer is visible for all your partners (both current and future).

visibleForPartnerIds

list of strings List of partner identifiers. When partner is on this list then this offer is visible for him and he can use this offer in his Checkout Requests. This attribute is mutually exclusive with visibleForAllPartners - when offer is visible for all partners then this attribute has no effect.

metadata

metadata 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
}
				

Create a Cross-Sale Offer

Creates a cross-sale offer object.

Arguments

charge

object, optional (either charge or subscription is required) Defines charge that will be created when this cross-sale offer is bought. Can contain following attributes:

• amount (integer, required) - Charge amount in minor units of given currency
• currency (string, required) - Charge currency represented as three-letter ISO currency code
• capture (boolean, optional, default is true) - Whether this charge should be immediately captured

For more information about meaning of these attributes see charge create request.

subscription

object, optional (either charge or subscription is required) Defines subscription that will be created when this cross-sale offer is bought. Can contain following attributes:

• planId (string, required) - Identifier of a plan that will be assigned to this subscription
• captureCharges (boolean, optional, default is true) - Whatever charges created by this subscription will be immediately captured

For more information about meaning of these attributes see subscription create request.

template

string, required Name of template that will be used to display this offer in Checkout. Possible values are: image_and_text, text_only.

title

string, required Title that will be displayed when this offer is shown in Checkout.

description

string, optional Description that will be displayed when this offer is shown in Checkout.

imageData

string, optional Content of image file encoded in base64. Following types of images are supported: .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.

companyName

string, required Name of your company that will be displayed when this offer is shown in Checkout.

companyLocation

string, required Two letter ISO country code that defines location of your company. This location will be displayed when this offer is shown in Checkout.

termsAndConditionsUrl

string, required URL to your terms and conditions page. This URL will be used when this offer is shown in Checkout.

visibleForAllPartners

boolean, optional Whether this offer is visible for all your partners (both current and future).

visibleForPartnerIds

list of strings, optional List of partner identifiers. When partner is on this list then this offer is visible for him and he can use this offer in his Checkout Requests. This parameter is mutually exclusive with visibleForAllPartners - when offer is visible for all partners then this parameter has no effect.

metadata

metadata object, optional

Result

Successful request returns a cross-sale offer object that represents created cross-sale offer.

POST https://api.securionpay.com/cross-sale-offers
				

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"
				

{
	"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

Retrieve an existing cross-sale offer object.

Arguments

crossSaleOfferId

string, required Identifier of cross-sale offer object that should be retrieved.

Result

Successful request returns a cross-sale offer object.

GET https://api.securionpay.com/cross-sale-offers/{CROSS_SALE_OFFER_ID}
				

curl https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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

Update an existing cross-sale offer object.

Any not provided parameter will be left unchanged.

Arguments

crossSaleOfferId

string, required Identifier of cross-sale offer object that should be update.

charge

object, optional (either charge or subscription can be present) Defines charge that will be created when this cross-sale offer is bought. Can contain following attributes:

• amount (integer, required) - Charge amount in minor units of given currency
• currency (string, required) - Charge currency represented as three-letter ISO currency code
• capture (boolean, optional, default is true) - Whether this charge should be immediately captured

For more information about meaning of these attributes see charge create request.

subscription

object, optional (either charge or subscription can be present) Defines subscription that will be created when this cross-sale offer is bought. Can contain following attributes:

• planId (string, required) - Identifier of a plan that will be assigned to this subscription
• captureCharges (boolean, optional, default is true) - Whatever charges created by this subscription will be immediately captured

For more information about meaning of these attributes see subscription create request.

template

string, optional Name of template that will be used to display this offer in Checkout. Possible values are: image_and_text, text_only.

title

string, optional Title that will be displayed when this offer is shown in Checkout.

description

string, optional Description that will be displayed when this offer is shown in Checkout.

imageData

string, optional Content of image file encoded in base64. Following types of images are supported: .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.

companyName

string, optional Name of your company that will be displayed when this offer is shown in Checkout.

companyLocation

string, optional Two letter ISO country code that defines location of your company. This location will be displayed when this offer is shown in Checkout.

termsAndConditionsUrl

string, optional URL to your terms and conditions page. This URL will be used when this offer is shown in Checkout.

visibleForAllPartners

boolean, optional Whether this offer is visible for all your partners (both current and future).

visibleForPartnerIds

list of strings, optional List of partner identifiers. When partner is on this list then this offer is visible for him and he can use this offer in his Checkout Requests. This parameter is mutually exclusive with visibleForAllPartners - when offer is visible for all partners then this parameter has no effect.

metadata

metadata object, optional

Result

Successful request returns a cross-sale offer object that was updated.

POST https://api.securionpay.com/cross-sale-offers/{CROSS_SALE_OFFER_ID}
				

curl https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "title=Buy 500 gems"
				

{
	"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
}
				

Delete a Cross-Sale Offer

Deletes an existing cross-sale offer object.

Arguments

crossSaleOfferId

string, required Identifier of cross-sale offer object that should be deleted.

Result

Successful request returns identifier of deleted cross-sale offer object.

DELETE https://api.securionpay.com/cross-sale-offers/{CROSS_SALE_OFFER_ID}
				

curl https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X DELETE
				

{
	"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
}
				

List Cross-Sale Offers

List cross-sale offer objects.

Arguments

created

object, optional Filter results based on value of created attribute. Can have following attributes:

• gt - return objects created after given timestamp
• gte - return objects created after or exactly on given timestamp
• lt - return objects created before given timestamp
• lte - return objects created before or exactly on given timestamp

partnerId

string, optional Returns only offers owned by given partner. Special value self can be used to return only your offers.

deleted

boolean, optional (default is false) Can be used to list deleted cross-sale offers.

limit

integer, optional (default is 10) Limit the number of returned objects. Limit must be between 1 and 100.

startingAfterId

string, optional Cursor used for pagination (getting next page). For example, if you make a list request and receive 10 objects, where last object have id=some-example-id - then you can make another request with startingAfterId=some-example-id to get next page of that list.

endingBeforeId

string, optional Cursor used for pagination (getting previous page). For example, if you make a list request and receive 10 objects, where first object have id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get previous page of that list.

Result

Successful request returns a list of cross-sale offer objects.

Results are sorted by creation date, with most recent objects first.

GET https://api.securionpay.com/cross-sale-offers
				

curl "https://api.securionpay.com/cross-sale-offers?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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
}
				

Credits

Credit represents funds transfer to a card.

This feature is available for selected business models only. Please contact [email protected] to find out more.

Credit object

Attributes

id

string

created

timestamp

objectType

string (value is always "credit")

amount

integer Credit amount in minor units of given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".

currency

string Credit currency represented as three-letter ISO currency code.

description

string

card

card object Card that was used to create this credit.

customerId

string Identifier of customer who is owner of this credit or null if this credit is not associated with any customer.

threeDSecureInfo

object Additional data present if card used to create this credit was verified with 3D Secure. Can contain following attributes:

• amount (integer) - amount in minor units that was used in 3D Secure
• currency (string) - currency that was used in 3D Secure (represented as three-letter ISO currency code)
• enrolled (boolean) - whatever card used to create this credit supports 3D Secure
• liabilityShift (string) - can have one of following values:
  successful - 3D Secure was completed successfully
  failed - 3D Secure is supported, but was not completed successfully
  not_possible - 3D Secure is not supported

metadata

metadata object

failureCode

string Error code that describes why credit has failed. Only present in failed credits. For list of possible values see code attribute in error object.

failureMessage

string Human-readable message that describes why credit has failed. Only present in failed credits.

{
	"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",
	  "country" : "CH"
	},
	"customerId" : null,
	"metadata" : {}
}
				

Create a new Credit

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.

Arguments

amount

integer, required Credit amount in minor units of given currency. For example 10€ is represented as "1000" and 10¥ is represented as "10".

currency

string, required Credit currency represented as three-letter ISO currency code.

description

string, optional

customerId

string, optional (either customerId or card is required) Identifier of customer that will be associated with this credit. This field is required if credit is being created with customer's existing card. If specified then successful charge created with new card will add that card to customer's cards and it will be set as customer's default card.

card

card token, card details or card identifier, optional (either customerId or card is required) Can be one of following:

• card token (for example obtained from custom form)
• card details (same as in card create request)
• card identifier (must be an existing card that is associated with customer specified in customerId field)

If card is not provided then customer's default card will be used.

metadata

metadata object, optional

Result

Successful request returns a credit object that represents created credit.

POST https://api.securionpay.com/credits
				

curl https://api.securionpay.com/credits \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "amount=499" \
	-d "currency=EUR" \
	-d "card=tok_NGsyDoJQXop5Pqqi6HizbJTe" \
	-d "description=Example credit"
				

{
	"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",
	  "country" : "CH"
	}
}
				

Retrieve an existing Credit

Retrieve an existing credit object.

This feature is available for selected business models only. Please contact [email protected] to find out more.

Arguments

creditId

string, required Identifier of credit object that should be retrieved.

Result

Successful request returns a credit object.

GET https://api.securionpay.com/credits/{CREDIT_ID}
				

curl https://api.securionpay.com/credits/cr_OwM7B3WWha5SIfjNSw2eUqVb \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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",
	  "country" : "CH"
	}
}
				

Update an existing Credit

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.

Arguments

creditId

string, required Identifier of credit object that should be updated.

customerId

string, optional Identifier of customer that will be associated with this credit. Updating this field is only possible for credit that is not assigned to any customer. Assigning successful credit to customer will add card that was used to create that credit to customer's cards and is will be set as customer's default card.

description

string, optional

metadata

metadata object, optional

Result

Successful request returns a credit object that was updated.

POST https://api.securionpay.com/credits/{CREDIT_ID}
				

curl https://api.securionpay.com/credits/cr_OwM7B3WWha5SIfjNSw2eUqVb \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "description=New description"
				

{
	"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",
	  "country" : "CH"
	}
}
				

List Credit

List credit objects.

This feature is available for selected business models only. Please contact [email protected] to find out more.

Arguments

created

object, optional Filter results based on value of created attribute. Can have following attributes:

• gt - return objects created after given timestamp
• gte - return objects created after or exactly on given timestamp
• lt - return objects created before given timestamp
• lte - return objects created before or exactly on given timestamp

customerId

string, optional Returns only credits associated with given customer.

limit

integer, optional (default is 10) Limit the number of returned objects. Limit must be between 1 and 100.

startingAfterId

string, optional Cursor used for pagination (getting next page). For example, if you make a list request and receive 10 objects, where last object have id=some-example-id - then you can make another request with startingAfterId=some-example-id to get next page of that list.

endingBeforeId

string, optional Cursor used for pagination (getting previous page). For example, if you make a list request and receive 10 objects, where first object have id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get previous page of that list.

Result

Successful request returns a list of credit objects.

Results are sorted by creation date, with most recent objects first.

GET https://api.securionpay.com/credits
				

curl "https://api.securionpay.com/credits?limit=3" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"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",
			  "country" : "CH"
			}
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}
				

Disputes

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.

File Uploads

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.

Fraud Warnings

Fraud Warning represents information received from card issuer regarding charge.

Fraud Warning object

Attributes

id

string

created

timestamp

objectType

string (value is always "fraud_warning")

charge

charge object Charge associated with this fraud warning.

actionable

boolean Fraud warning is actionable if associated charge is not fully refunded and not disputed.

{
	"id" : "fw_O7FRMgfC5g9BFqjEFepcB07J",
	"created" : 1609325894,
	"objectType" : "fraud_warning",
	"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
	"actionable" : true
}
				

Retrieve an existing Fraud Warning

Retrieve an existing fraud warning object.

Arguments

fraudWarningId

string, required Identifier of fraud warning object that should be retrieved.

Result

Successful request returns a fraud warning object.

GET https://api.securionpay.com/fraud-warnings/{FRAUD_WARNING_ID}
				

curl https://api.securionpay.com/fraud-warnings/fw_O7FRMgfC5g9BFqjEFepcB07J \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"id" : "fw_O7FRMgfC5g9BFqjEFepcB07J",
	"created" : 1609325894,
	"objectType" : "fraud_warning",
	"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
	"actionable" : true
}
				

List Fraud Warnings

List fraud warning objects.

Arguments

created

object, optional Filter results based on value of created attribute. Can have following attributes:

• gt - return objects created after given timestamp
• gte - return objects created after or exactly on given timestamp
• lt - return objects created before given timestamp
• lte - return objects created before or exactly on given timestamp

limit

integer, optional (default is 10) Limit the number of returned objects. Limit must be between 1 and 100.

startingAfterId

string, optional Cursor used for pagination (getting next page). For example, if you make a list request and receive 10 objects, where last object have id=some-example-id - then you can make another request with startingAfterId=some-example-id to get next page of that list.

endingBeforeId

string, optional Cursor used for pagination (getting previous page). For example, if you make a list request and receive 10 objects, where first object have id=some-example-id - then you can make another request with endingBeforeId=some-example-id to get previous page of that list.

charge

string, optional Identifier of charge object for which fraud warnings should be listed.

Result

Successful request returns a list of fraud-warning objects.

Results are sorted by creation date, with most recent objects first.

GET https://api.securionpay.com/fraud-warnings
				

curl "https://api.securionpay.com/fraud-warnings" \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

{
	"list" : [
		{
			"id" : "fw_O7FRMgfC5g9BFqjEFepcB07J",
			"created" : 1609325894,
			"objectType" : "fraud_warning",
			"charge" : "char_ZNmWK4pUECfFQTY0N4WMKeh3",
			"actionable" : true
		},
		{ ... },
		{ ... }
	],
	"hasMore" : true
}