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.

API ENDPOINT


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.

EXAMPLE REQUEST


curl https://api.securionpay.com/charges \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				
Note: adding colon after API key will prevent curl from asking for password

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.

HTTP Status codes


200 OK - Successful request
400 Bad Request - Request has invalid data or is missing a required field
401 Unauthorized - Provided API key is missing or invalid
402 Payment failed - Request was valid but card processing has failed
404 Not Found - Requested object was not found
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
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.

EXAMPLE ERROR RESPONSE


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


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

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.

EXAMPLE OBJECT


{
	"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
	"created" : 1415810511,
	"objectType" : "charge",
	"amount" : 499,
	"currency" : "EUR",
	"description" : "Example charge",
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"brand" : "Visa",
		"type" : "Credit Card"
	},
	"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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
	"created" : 1415810511,
	"objectType" : "charge",
	"amount" : 499,
	"currency" : "EUR",
	"description" : "Example charge",
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"cardholderName" : "John Doe",
		"brand" : "Visa",
		"type" : "Credit Card"
	},
	"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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
	"created" : 1415810511,
	"objectType" : "charge",
	"amount" : 499,
	"currency" : "EUR",
	"description" : "Example charge",
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"cardholderName" : "John Doe",
		"brand" : "Visa",
		"type" : "Credit Card"
	},
	"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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
	"created" : 1415810511,
	"objectType" : "charge",
	"amount" : 499,
	"currency" : "EUR",
	"description" : "New description",
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"cardholderName" : "John Doe",
		"brand" : "Visa",
		"type" : "Credit Card"
	},
	"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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
	"created" : 1415810511,
	"objectType" : "charge",
	"amount" : 499,
	"currency" : "EUR",
	"description" : "Example charge",
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"cardholderName" : "John Doe",
		"brand" : "Visa",
		"type" : "Credit Card"
	},
	"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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
	"created" : 1415810511,
	"objectType" : "charge",
	"amount" : 499,
	"currency" : "EUR",
	"description" : "Example charge",
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"cardholderName" : "John Doe",
		"brand" : "Visa",
		"type" : "Credit Card"
	},
	"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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

Successful request returns a list of charge objects.

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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"list" : [
		{
			"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
			"created" : 1415810511,
			"objectType" : "charge",
			"amount" : 499,
			"currency" : "EUR",
			"description" : "Example charge",
			"card" : {
				"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
				"created" : 1415810511,
				"objectType" : "card",
				"first6" : "424242",
				"last4" : "4242",
				"fingerprint" : "e3d8suyIDgFg3pE7",
				"expMonth" : "11",
				"expYear" : "2022",
				"cardholderName" : "John Doe",
				"brand" : "Visa",
				"type" : "Credit Card"
			},
			"captured" : true,
			"refunded" : false,
			"disputed" : false
		},
		{ ... },
		{ ... }
	],
	"totalCount" : 25
}
				

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

EXAMPLE OBJECT


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

EXAMPLE OBJECT


{
	"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"created" : 1415810511,
	"objectType" : "customer",
	"email" : "[email protected]",
	"description" : null,
	"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
	"cards" : [
		{
			"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			"created" : 1415810511,
			"objectType" : "card",
			"first6" : "424242",
			"last4" : "4242",
			"fingerprint" : "e3d8suyIDgFg3pE7",
			"expMonth" : "11",
			"expYear" : "2022",
			"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			"brand" : "Visa",
			"type" : "Credit Card"
		}
	],
	"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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"created" : 1415810511,
	"objectType" : "customer",
	"email" : "[email protected]",
	"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
	"cards" : [
		{
			"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			"created" : 1415810511,
			"objectType" : "card",
			"first6" : "424242",
			"last4" : "4242",
			"fingerprint" : "e3d8suyIDgFg3pE7",
			"expMonth" : "11",
			"expYear" : "2022",
			"cardholderName" : "John Doe",
			"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			"brand" : "Visa",
			"type" : "Credit Card"
		}
	]
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"created" : 1415810511,
	"objectType" : "customer",
	"email" : "[email protected]",
	"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
	"cards" : [
		{
			"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			"created" : 1415810511,
			"objectType" : "card",
			"first6" : "424242",
			"last4" : "4242",
			"fingerprint" : "e3d8suyIDgFg3pE7",
			"expMonth" : "11",
			"expYear" : "2022",
			"cardholderName" : "John Doe",
			"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			"brand" : "Visa",
			"type" : "Credit Card"
		}
	]
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"created" : 1415810511,
	"objectType" : "customer",
	"email" : "[email protected]",
	"description" : "New description",
	"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
	"cards" : [
		{
			"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			"created" : 1415810511,
			"objectType" : "card",
			"first6" : "424242",
			"last4" : "4242",
			"fingerprint" : "e3d8suyIDgFg3pE7",
			"expMonth" : "11",
			"expYear" : "2022",
			"cardholderName" : "John Doe",
			"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			"brand" : "Visa",
			"type" : "Credit Card"
		}
	]
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
}
				

List 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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

Successful request returns a list of customer objects.

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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"list" : [
		{
			"id" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			"created" : 1415810511,
			"objectType" : "customer",
			"email" : "[email protected]",
			"defaultCardId" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			"cards" : [
				{
					"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
					"created" : 1415810511,
					"objectType" : "card",
					"first6" : "424242",
					"last4" : "4242",
					"fingerprint" : "e3d8suyIDgFg3pE7",
					"expMonth" : "11",
					"expYear" : "2022",
					"cardholderName" : "John Doe",
					"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
					"brand" : "Visa",
					"type" : "Credit Card"
				}
			]
		},
		{ ... },
		{ ... }
	],
	"totalCount" : 25
}
				

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, Discover, JCB, Diners Club, Unknown
type
string Type of card. Possible values are: Credit Card, Debit Card, Unknown
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

EXAMPLE OBJECT


{
	"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
	"created" : 1415810511,
	"objectType" : "card",
	"first6" : "424242",
	"last4" : "4242",
	"fingerprint" : "e3d8suyIDgFg3pE7",
	"expMonth" : "11",
	"expYear" : "2022",
	"cardholderName" : "John Doe",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"brand" : "Visa",
	"type" : "Credit Card",
	"addressCountry" : null,
	"addressCity" : null,
	"addressState" : null,
	"addressZip" : null,
	"addressLine1" : null,
	"addressLine2" : 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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
	"created" : 1415810511,
	"objectType" : "card",
	"first6" : "424242",
	"last4" : "4242",
	"fingerprint" : "e3d8suyIDgFg3pE7",
	"expMonth" : "11",
	"expYear" : "2022",
	"cardholderName" : "John Doe",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"brand" : "Visa",
	"type" : "Credit Card",
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
	"created" : 1415810511,
	"objectType" : "card",
	"first6" : "424242",
	"last4" : "4242",
	"fingerprint" : "e3d8suyIDgFg3pE7",
	"expMonth" : "11",
	"expYear" : "2022",
	"cardholderName" : "John Doe",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"brand" : "Visa",
	"type" : "Credit Card"
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
	"created" : 1415810511,
	"objectType" : "card",
	"first6" : "424242",
	"last4" : "4242",
	"fingerprint" : "e3d8suyIDgFg3pE7",
	"expMonth" : "11",
	"expYear" : "2022",
	"cardholderName" : "Jane Doe",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"brand" : "Visa",
	"type" : "Credit Card"
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
}
				

List 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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

Successful request returns a list of card objects.

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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"list" : [
		{
			"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			"created" : 1415810511,
			"objectType" : "card",
			"first6" : "424242",
			"last4" : "4242",
			"fingerprint" : "e3d8suyIDgFg3pE7",
			"expMonth" : "11",
			"expYear" : "2022",
			"cardholderName" : "John Doe",
			"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			"brand" : "Visa",
			"type" : "Credit Card"
		},
		{ ... },
		{ ... }
	],
	"totalCount" : 5
}
				

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

EXAMPLE OBJECT


{
	"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
	"created" : 1415982733,
	"objectType" : "subscription",
	"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"quantity" : 1,
	"status" : "active",
	"remainingBillingCycles" : null,
	"start" : 1415982733,
	"currentPeriodStart" : 1415982733,
	"currentPeriodEnd" : 1416846733,
	"canceledAt" : null,
	"endedAt" : null,
	"trialStart" : null,
	"trialEnd" : null,
	"cancelAtPeriodEnd" : false,
	"metadata" : {}
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
	"created" : 1415982733,
	"objectType" : "subscription",
	"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"quantity" : 1,
	"status" : "active",
	"start" : 1415982733,
	"currentPeriodStart" : 1415982733,
	"currentPeriodEnd" : 1416846733,
	"cancelAtPeriodEnd" : false
}
				

Retrieve an existing Subscription

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
	"created" : 1415982733,
	"objectType" : "subscription",
	"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"quantity" : 1,
	"status" : "active",
	"start" : 1415982733,
	"currentPeriodStart" : 1415982733,
	"currentPeriodEnd" : 1416846733,
	"cancelAtPeriodEnd" : false
}
				

Update an existing Subscription

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
	"created" : 1415982733,
	"objectType" : "subscription",
	"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"quantity" : 5,
	"status" : "active",
	"start" : 1415982733,
	"currentPeriodStart" : 1415982733,
	"currentPeriodEnd" : 1416846733,
	"cancelAtPeriodEnd" : false
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE REQUEST (with atPeriodEnd)


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

EXAMPLE RESPONSE


{
	"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
	"created" : 1415982733,
	"objectType" : "subscription",
	"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
	"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
	"quantity" : 1,
	"status" : "canceled",
	"start" : 1415982733,
	"currentPeriodStart" : 1415982733,
	"currentPeriodEnd" : 1416846733,
	"canceledAt" : 1415982979,
	"endedAt" : 1415982979,
	"cancelAtPeriodEnd" : false
}
				

List 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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

Successful request returns a list of subscription objects.

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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"list" : [
		{
			"id" : "sub_vrEaVmRDW0oKz8ycyy8Yc4l5",
			"created" : 1415982733,
			"objectType" : "subscription",
			"planId" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
			"customerId" : "cust_AoR0wvgntQWRUYMdZNLYMz5R",
			"quantity" : 1,
			"status" : "active",
			"start" : 1415982733,
			"currentPeriodStart" : 1415982733,
			"currentPeriodEnd" : 1416846733,
			"cancelAtPeriodEnd" : false
		},
		{ ... },
		{ ... }
	],
	"totalCount" : 25
}
				

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

EXAMPLE OBJECT


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

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

DEFINITION


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

EXAMPLE REQUEST


curl https://api.securionpay.com/plans \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "amount=499" \
	-d "currency=EUR" \
	-d "interval=day" \
	-d "intervalCount=10" \
	-d "name=Example plan"
				

EXAMPLE RESPONSE


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

Retrieve an existing Plan

Retrieve an existing plan object.

Arguments

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

Result

Successful request returns a plan object.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


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

Update an existing Plan

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


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

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "plan_bLu3vzO8yhAFhbxFEadm6HUV",
}
				

List 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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

Successful request returns a list of plan objects.

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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


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

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.

EXAMPLE OBJECT


{
	"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
	"created" : 1416305114,
	"objectType" : "event",
	"type" : "CHARGE_SUCCEEDED",
	"data" : {
		"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
		"created" : 1415810511,
		"objectType" : "charge",
		"amount" : 499,
		"currency" : "EUR",
		"description" : "Example charge",
		"card" : {
			"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			"created" : 1415810511,
			"objectType" : "card",
			"first6" : "424242",
			"last4" : "4242",
			"fingerprint" : "e3d8suyIDgFg3pE7",
			"expMonth" : "11",
			"expYear" : "2022",
			"cardholderName" : "John Doe",
			"brand" : "Visa",
			"type" : "Credit Card"
		},
		"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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
	"created" : 1416305114,
	"objectType" : "event",
	"type" : "CHARGE_SUCCEEDED",
	"data" : {
		"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
		"created" : 1415810511,
		"objectType" : "charge",
		"amount" : 499,
		"currency" : "EUR",
		"description" : "Example charge",
		"card" : {
			"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
			"created" : 1415810511,
			"objectType" : "card",
			"first6" : "424242",
			"last4" : "4242",
			"fingerprint" : "e3d8suyIDgFg3pE7",
			"expMonth" : "11",
			"expYear" : "2022",
			"cardholderName" : "John Doe",
			"brand" : "Visa",
			"type" : "Credit Card"
		},
		"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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

Successful request returns a list of event objects.

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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"list" : [
		{
			"id" : "event_EY7CzyQiffJykW8rC5wSRnAj",
			"created" : 1416305114,
			"objectType" : "event",
			"type" : "CHARGE_SUCCEEDED",
			"data" : {
				"id" : "char_ORVCrwOrTkGsDwM3H50OIW7Q",
				"created" : 1415810511,
				"objectType" : "charge",
				"amount" : 499,
				"currency" : "EUR",
				"description" : "Example charge",
				"card" : {
					"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
					"created" : 1415810511,
					"objectType" : "card",
					"first6" : "424242",
					"last4" : "4242",
					"fingerprint" : "e3d8suyIDgFg3pE7",
					"expMonth" : "11",
					"expYear" : "2022",
					"cardholderName" : "John Doe",
					"brand" : "Visa",
					"type" : "Credit Card"
				},
				"captured" : true,
				"refunded" : false,
				"disputed" : false
			},
			"log" : "log_2KzhaJZBmylL40iGiHfZsKRm"
		},
		{ ... },
		{ ... }
	],
	"totalCount" : 25
}
				

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.
CUSTOMER_RECORD_CREATED
Occurs when new customer record is created. Event data is a customer record object.
CUSTOMER_RECORD_REFRESHED
Occurs when customer record is refreshed. Event data is a customer record object.
CUSTOMER_RECORD_FEE_RECEIVED
Occurs when new customer record fee is received. Event data is a customer record fee object.
CUSTOMER_RECORD_PROFIT_RECEIVED
Occurs when new customer record profit is received. Event data is a customer record profit 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

EXAMPLE OBJECT


{
	"id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
	"created" : 1415810511,
	"objectType" : "token",
	"first6" : "424242",
	"last4" : "4242",
	"fingerprint" : "e3d8suyIDgFg3pE7",
	"expMonth" : "11",
	"expYear" : "2022",
	"brand" : "Visa",
	"type" : "Credit Card",
	"cardholderName" : "John Doe",
	"used" : true,
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"brand" : "Visa",
		"type" : "Credit Card"
	},
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


curl https://api.securionpay.com/tokens \
	-u pu_test_WVMFC9GFuvm54b0uorifKkCh: \
	-d "number=4242424242424242" \
	-d "expMonth=11" \
	-d "expYear=2022" \
	-d "cvc=123" \
	-d "cardholderName=John Doe"
				

EXAMPLE RESPONSE


{
	"id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
	"created" : 1415810511,
	"objectType" : "token",
	"first6" : "424242",
	"last4" : "4242",
	"fingerprint" : "e3d8suyIDgFg3pE7",
	"expMonth" : "11",
	"expYear" : "2022",
	"brand" : "Visa",
	"type" : "Credit Card",
	"cardholderName" : "John Doe",
	"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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "tok_NGsyDoJQXop5Pqqi6HizbJTe",
	"created" : 1415810511,
	"objectType" : "token",
	"first6" : "424242",
	"last4" : "4242",
	"fingerprint" : "e3d8suyIDgFg3pE7",
	"expMonth" : "11",
	"expYear" : "2022",
	"brand" : "Visa",
	"type" : "Credit Card",
	"cardholderName" : "John Doe",
	"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.

EXAMPLE OBJECT


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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


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

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "blr_O3y7VyxbszuezuDNjuBsExUf",
}
				

List Blacklist 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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

Successful request returns a list of blacklist rule objects.

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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


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

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. Note that preselecting "remember-me" is all you need to do to become a data-provider and profit from Customer Records that you helped to create.
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)

EXAMPLE CHECKOUT REQUEST (with charge)


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

EXAMPLE CHECKOUT REQUEST (with subscription)


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

EXAMPLE CHECKOUT REQUEST (with custom charge)


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

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 )

EXAMPLE SIGNING


export checkout_request='{"charge":{"amount":499,"currency":"EUR"}}'
export signature=`echo -n "$checkout_request" | openssl dgst -sha256 -hmac 'pr_test_tXHm9qV9qV9bjIRHcQr9PLPa' | sed 's/^.* //'`
echo -n "$signature|$checkout_request" | base64
				

EXAMPLE SIGNED CHECKOUT REQUEST


Y2Y5Y2UyZDgzMzFjNTMxZjgzODlhNjE2YTE4Zjk1NzhjMTM0Yjc4NGRhYjVjYjdlNGI1OTY0ZTc3OTBmMTczY3x7ImNoYXJnZSI6eyJhbW91bnQiOjQ5OSwiY3VycmVuY3kiOiJFVVIifX0=
				

Cross-Sale Offers

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

EXAMPLE OBJECT


{
	"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
	"created" : 1442323521,
	"objectType" : "crossSaleOffer",
	"charge" : {
		"amount" : 499,
		"currency" : "EUR",
		"capture" : true
	},
	"template" : "image_and_text",
	"title" : "Buy 1000 gold coins",
	"description" : "And get another 1000 for free",
	"imageUrl" : "https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J/images/img_sTk23tRerAj1mwkzL8s3p5Oj",
	"companyName" : "SecurionPay",
	"companyLocation" : "CH",
	"termsAndConditionsUrl" : "https://securionpay.com/docs/terms",
	"visibleForAllPartners" : true
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


curl https://api.securionpay.com/cross-sale-offers \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "charge[amount]=499" \
	-d "charge[currency]=EUR" \
	-d "template=image_and_text" \
	-d "title=Buy 1000 gold coins" \
	-d "description=And get another 1000 for free" \
	-d "imageData=iVBORw0KGgoAAAANSUhEUgAAAB4AAAAeCAYAAAA7MK6iAAAAMUlEQVRIx%2B3NsQ0AMAzDMKf%2F%2F5yeUG9dqFkAZ5NN0VRXP558CgwGg8FgMBgMBoPB7y7UlAQ6IWgPUwAAAABJRU5ErkJggg==" \
	-d "companyName=SecurionPay" \
	-d "companyLocation=CH" \
	-d "termsAndConditionsUrl=https://securionpay.com/docs/terms" \
	-d "visibleForAllPartners=true"
				

EXAMPLE RESPONSE


{
	"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
	"created" : 1442323521,
	"objectType" : "crossSaleOffer",
	"charge" : {
		"amount" : 499,
		"currency" : "EUR",
		"capture" : true
	},
	"template" : "image_and_text",
	"title" : "Buy 1000 gold coins",
	"description" : "And get another 1000 for free",
	"imageUrl" : "https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J/images/img_sTk23tRerAj1mwkzL8s3p5Oj",
	"companyName" : "SecurionPay",
	"companyLocation" : "CH",
	"termsAndConditionsUrl" : "https://securionpay.com/docs/terms",
	"visibleForAllPartners" : true
}
				

Retrieve an existing Cross-Sale Offer

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
	"created" : 1442323521,
	"objectType" : "crossSaleOffer",
	"charge" : {
		"amount" : 499,
		"currency" : "EUR",
		"capture" : true
	},
	"template" : "image_and_text",
	"title" : "Buy 1000 gold coins",
	"description" : "And get another 1000 for free",
	"imageUrl" : "https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J/images/img_sTk23tRerAj1mwkzL8s3p5Oj",
	"companyName" : "SecurionPay",
	"companyLocation" : "CH",
	"termsAndConditionsUrl" : "https://securionpay.com/docs/terms",
	"visibleForAllPartners" : true
}
				

Update an existing Cross-Sale Offer

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
	"created" : 1442323521,
	"objectType" : "crossSaleOffer",
	"charge" : {
		"amount" : 499,
		"currency" : "EUR",
		"capture" : true
	},
	"template" : "image_and_text",
	"title" : "Buy 500 gems",
	"description" : "And get another 1000 for free",
	"imageUrl" : "https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J/images/img_sTk23tRerAj1mwkzL8s3p5Oj",
	"companyName" : "SecurionPay",
	"companyLocation" : "CH",
	"termsAndConditionsUrl" : "https://securionpay.com/docs/terms",
	"visibleForAllPartners" : true
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
}
				

List Cross-Sale 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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

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

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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"list" : [
		{
			"id" : "cso_SoxXo8cNBOrM9W1buW9xgR2J",
			"created" : 1442323521,
			"objectType" : "crossSaleOffer",
			"charge" : {
				"amount" : 499,
				"currency" : "EUR",
				"capture" : true
			},
			"template" : "image_and_text",
			"title" : "Buy 1000 gold coins",
			"description" : "And get another 1000 for free",
			"imageUrl" : "https://api.securionpay.com/cross-sale-offers/cso_SoxXo8cNBOrM9W1buW9xgR2J/images/img_sTk23tRerAj1mwkzL8s3p5Oj",
			"companyName" : "SecurionPay",
			"companyLocation" : "CH",
			"termsAndConditionsUrl" : "https://securionpay.com/docs/terms",
			"visibleForAllPartners" : true
		},
		{ ... },
		{ ... }
	],
	"totalCount" : 25
}
				

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.

EXAMPLE OBJECT


{
	"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
	"created" : 1415810511,
	"objectType" : "credit",
	"amount" : 499,
	"currency" : "EUR",
	"description" : "Example credit",
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"brand" : "Visa",
		"type" : "Credit Card"
	},
	"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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
	"created" : 1415810511,
	"objectType" : "credit",
	"amount" : 499,
	"currency" : "EUR",
	"description" : "Example credit",
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"cardholderName" : "John Doe",
		"brand" : "Visa",
		"type" : "Credit Card"
	}
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
	"created" : 1415810511,
	"objectType" : "credit",
	"amount" : 499,
	"currency" : "EUR",
	"description" : "Example credit",
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"cardholderName" : "John Doe",
		"brand" : "Visa",
		"type" : "Credit Card"
	}
}
				

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.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
	"created" : 1415810511,
	"objectType" : "credit",
	"amount" : 499,
	"currency" : "EUR",
	"description" : "New description",
	"card" : {
		"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
		"created" : 1415810511,
		"objectType" : "card",
		"first6" : "424242",
		"last4" : "4242",
		"fingerprint" : "e3d8suyIDgFg3pE7",
		"expMonth" : "11",
		"expYear" : "2022",
		"cardholderName" : "John Doe",
		"brand" : "Visa",
		"type" : "Credit Card"
	}
}
				

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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

Successful request returns a list of credit objects.

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

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"list" : [
		{
			"id" : "cr_OwM7B3WWha5SIfjNSw2eUqVb",
			"created" : 1415810511,
			"objectType" : "credit",
			"amount" : 499,
			"currency" : "EUR",
			"description" : "Example credit",
			"card" : {
				"id" : "card_8P7OWXA5xiTS1ISnyZcum1KV",
				"created" : 1415810511,
				"objectType" : "card",
				"first6" : "424242",
				"last4" : "4242",
				"fingerprint" : "e3d8suyIDgFg3pE7",
				"expMonth" : "11",
				"expYear" : "2022",
				"cardholderName" : "John Doe",
				"brand" : "Visa",
				"type" : "Credit Card"
			},
		},
		{ ... },
		{ ... }
	],
	"totalCount" : 25
}
				

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.

Dispute object

Attributes

id
string
created
timestamp
objectType
string (value is always "dispute")
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 Current status of this dispute. Possible values are:
  • RETRIEVAL_REQUEST_NEW - retrieval request, response needed
  • RETRIEVAL_REQUEST_RESPONSE_UNDER_REVIEW - retrieval request, response under review
  • RETRIEVAL_REQUEST_REPRESENTED - retrieval request, successfully represented
  • CHARGEBACK_NEW - chargeback, response needed
  • CHARGEBACK_RESPONSE_UNDER_REVIEW - chargeback, response under review
  • CHARGEBACK_REPRESENTED_SUCCESSFULLY - chargeback, dispute won
  • CHARGEBACK_REPRESENTED_UNSUCCESSFULLY - chargeback, dispute lost
reason
string Reason why customer created this dispute. Possible values are: FRAUDULENT, UNRECOGNIZED, DUPLICATE, SUBSCRIPTION_CANCELED, PRODUCT_NOT_RECEIVED, PRODUCT_UNACCEPTABLE, CREDIT_NOT_PROCESSED, GENERAL
acceptedAsLost
boolean Whatever this dispute is closed and automatically lost as result of that.
charge
charge object Charge associated with this dispute.
evidence
dispute evidence object Evidence object that was created for this dispute.
evidenceDetails
object Attributes:
  • hasEvidence (boolean)
  • submissionCount (integer)

EXAMPLE RESPONSE


{
	"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
	"created" : 1489571590,
	"objectType" : "dispute",
	"updated" : 1489571590,
	"amount" : 1000,
	"currency" : "EUR",
	"status" : "CHARGEBACK_NEW",
	"reason" : "GENERAL",
	"acceptedAsLost" : false,
	"charge" : {
		"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
		"created" : 1489571590,
		"objectType" : "charge",
		"amount" : 0,
		"currency" : "EUR",
		"card" : {
			"id" : "card_bF07BXcvdyPW4Mq6aW8lRK5l",
			"created" : 1489571590,
			"objectType" : "card",
			"first6" : "424200",
			"last4" : "0018",
			"fingerprint" : "k7766nfnZcWDhUv1",
			"expMonth" : "4",
			"expYear" : "2018",
			"brand" : "Visa",
			"type" : "Credit Card"
		},
		"captured" : true,
		"refunded" : false,
		"disputed" : true
	},
	"evidence" : {
		"productDescription" : "Exclusive black shoes",
		"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
	},
	"evidenceDetails" : {
		"hasEvidence" : true,
		"submissionCount" : 1
	}
}
				

Dispute Evidence object

Attributes

productDescription
string A description of a product or service purchased by customer with any details provided to the customer at the time of purchase.
customerName
string The name of the customer.
customerEmail
string Customer's email address provided in purchasing process.
customerPurchaseIp
string The IP address used by a customer while purchasing.
customerSignature
id of file upload A scanned image or a photo of a document showing the customer's signature.
billingAddress
string The billing address provided by the customer in the purchasing process.
receipt
id of file upload Receipts and messages sent to the customer with charge notification.
customerCommunication
id of file upload Any communication with a customer that can help you win the dispute. These could be emails with a proof of receiving the product or that the service was provided to the customer on the specified date.
serviceDate
string The date on which a customer received the purchased service, displayed in a human-readable format.
serviceDocumentation
id of file upload The documentation proving that the service was provided to the customer. It could be a copy of a signed contract, etc.
duplicateChargeId
string The ID of the duplicated charge.
duplicateChargeDocumentation
id of file upload Any documents with a proof that there were two or more separated transactions. Include shipping details, receipt, packing list, etc.
duplicateChargeExplanation
string Any information showing that transactions were separated to prove that the prior charge wasn't duplicated.
refundPolicy
id of file upload Your refund policy, as shown to the customer.
refundPolicyDisclosure
string An explanation showing how and when the customer agreed to your refund policy.
refundRefusalExplanation
string An explanation of why the customer is not entitled to a refund.
cancellationPolicy
id of file upload Your subscription cancellation policy, as shown to the customer.
cancellationPolicyDisclosure
string An explanation of how and when the customer agreed to your cancellation policy.
cancellationRefusalExplanation
string An explanation showing that a customer continued using the product after claimed date of cancellation.
accessActivityLogs
id of file upload Any evidence of customer's activity after the date they claim they canceled the subscription, such as server or activity logs, IP addresses, etc.
shippingAddress
string The shipping address to which a physical product was delivered. To maximize your chances of winning the dispute, the address should match a verified billing address.
shippingDate
string The date on which a physical product began its route to the shipping address, displayed in a human-readable format and prior to the date of the dispute.
shippingCarrier
string The name of the delivery service that shipped a physical product, eg. UPS, FedEx. If there are multiple carriers for the purchase, separate them with commas.
shippingTrackingNumber
string The number given by the delivery service for a physical product. If there are multiple tracking numbers for one purchase, separate them with commas.
shippingDocumentation
id of file upload Documentation with proof that cardholder received a product at the address provided in purchasing process. This could be a document with the full shipping address, such as the shipment receipt, etc.
uncategorizedText
string An explanation with further evidence that doesn't fit into any of the fields provided.
uncategorizedFile
id of file upload Any files or documents with further evidence that doesn't fit into any of the fields provided.

EXAMPLE RESPONSE


{
	"productDescription" : null,
	"customerName" : null,
	"customerEmail" : null,
	"customerPurchaseIp" : null,
	"customerSignature" : null,
	"billingAddress" : null,
	"receipt" : null,
	"customerCommunication" : null,
	"serviceDate" : null,
	"serviceDocumentation" : null,
	"duplicateChargeId" : null,
	"duplicateChargeDocumentation" : null,
	"duplicateChargeExplanation" : null,
	"refundPolicy" : null,
	"refundPolicyDisclosure" : null,
	"refundRefusalExplanation" : null,
	"cancellationPolicy" : null,
	"cancellationPolicyDisclosure" : null,
	"cancellationRefusalExplanation" : null,
	"accessActivityLogs" : null,
	"shippingAddress" : null,
	"shippingDate" : null,
	"shippingCarrier" : null,
	"shippingTrackingNumber" : null,
	"shippingDocumentation" : null,
	"uncategorizedText" : null,
	"uncategorizedFile" : null
}
			

Retrieve an existing Dispute

Retrieve an existing dispute object.

Arguments

disputeId
string, required Identifier of dispute object that should be retrieved.

Result

Successful request returns a dispute object.

DEFINITION


GET https://api.securionpay.com/disputes/{DISPUTE_ID}
			

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
	"created" : 1489571590,
	"objectType" : "dispute",
	"updated" : 1489571590,
	"amount" : 1000,
	"currency" : "EUR",
	"status" : "CHARGEBACK_NEW",
	"reason" : "GENERAL",
	"acceptedAsLost" : false,
	"charge" : {
		"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
		"created" : 1489571590,
		"objectType" : "charge",
		"amount" : 0,
		"currency" : "EUR",
		"card" : {
			"id" : "card_bF07BXcvdyPW4Mq6aW8lRK5l",
			"created" : 1489571590,
			"objectType" : "card",
			"first6" : "424200",
			"last4" : "0018",
			"fingerprint" : "k7766nfnZcWDhUv1",
			"expMonth" : "4",
			"expYear" : "2018",
			"brand" : "Visa",
			"type" : "Credit Card"
		},
		"captured" : true,
		"refunded" : false,
		"disputed" : true
	},
	"evidence" : {
		"productDescription" : "Exclusive black shoes",
		"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
	},
	"evidenceDetails" : {
		"hasEvidence" : true,
		"submissionCount" : 1
	}
}
				

Update an existing Dispute

Update an existing dispute object.

Any not provided parameter will be left unchanged.

Arguments

disputeId
string, required Identifier of dispute object that should be updated.
evidence
dispute evidence object, optional Updating any field in evidence will submit all field for review. Attributes:
  • productDescription (optional)
  • customerName (optional)
  • customerEmail (optional)
  • customerPurchaseIp (optional)
  • customerSignature (optional)
  • billingAddress (optional)
  • receipt (optional)
  • customerCommunication (optional)
  • serviceDate (optional)
  • serviceDocumentation (optional)
  • duplicateChargeId (optional)
  • duplicateChargeDocumentation (optional)
  • duplicateChargeExplanation (optional)
  • refundPolicy (optional)
  • refundPolicyDisclosure (optional)
  • refundRefusalExplanation (optional)
  • cancellationPolicy (optional)
  • cancellationPolicyDisclosure (optional)
  • cancellationRefusalExplanation (optional)
  • accessActivityLogs (optional)
  • shippingAddress (optional)
  • shippingDate (optional)
  • shippingCarrier (optional)
  • shippingTrackingNumber (optional)
  • shippingDocumentation (optional)
  • uncategorizedText (optional)
  • uncategorizedFile (optional)

Result

Successful request returns a dispute object.

DEFINITION


POST https://api.securionpay.com/disputes/{DISPUTE_ID}
				

EXAMPLE REQUEST


curl https://api.securionpay.com/disputes/disp_2nayTQXBBjaVEPVtCwGCbqOj \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-d "evidence[productDescription]=Exclusive black shoes" \
	-d "evidence[customerCommunication]=file_2nayTQXBBjaVEPVtCwGCbqOj"
			

EXAMPLE RESPONSE


{
	"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
	"created" : 1489571590,
	"objectType" : "dispute",
	"updated" : 1489571590,
	"amount" : 1000,
	"currency" : "EUR",
	"status" : "CHARGEBACK_NEW",
	"reason" : "GENERAL",
	"acceptedAsLost" : false,
	"charge" : {
		"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
		"created" : 1489571590,
		"objectType" : "charge",
		"amount" : 0,
		"currency" : "EUR",
		"card" : {
			"id" : "card_bF07BXcvdyPW4Mq6aW8lRK5l",
			"created" : 1489571590,
			"objectType" : "card",
			"first6" : "424200",
			"last4" : "0018",
			"fingerprint" : "k7766nfnZcWDhUv1",
			"expMonth" : "4",
			"expYear" : "2018",
			"brand" : "Visa",
			"type" : "Credit Card"
		},
		"captured" : true,
		"refunded" : false,
		"disputed" : true
	},
	"evidence" : {
		"productDescription" : "Exclusive black shoes",
		"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
	},
	"evidenceDetails" : {
		"hasEvidence" : true,
		"submissionCount" : 1
	}
}
				

Close an existing Dispute

Closing the dispute indicates that you do not want to submit any evidence and that you are acknowledging it as lost.

Arguments

disputeId
string, required Identifier of dispute object that should be closed.

Result

Successful request returns identifier of closed dispute object.

DEFINITION


POST https://api.securionpay.com/disputes/{DISPUTE_ID}/close
				

EXAMPLE REQUEST


curl https://api.securionpay.com/disputes/disp_2nayTQXBBjaVEPVtCwGCbqOj/close \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
	-X POST
			

EXAMPLE RESPONSE


{
	"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
	"created" : 1489571590,
	"objectType" : "dispute",
	"updated" : 1489571590,
	"amount" : 1000,
	"currency" : "EUR",
	"status" : "CHARGEBACK_NEW",
	"reason" : "GENERAL",
	"acceptedAsLost" : false,
	"charge" : {
		"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
		"created" : 1489571590,
		"objectType" : "charge",
		"amount" : 0,
		"currency" : "EUR",
		"card" : {
			"id" : "card_bF07BXcvdyPW4Mq6aW8lRK5l",
			"created" : 1489571590,
			"objectType" : "card",
			"first6" : "424200",
			"last4" : "0018",
			"fingerprint" : "k7766nfnZcWDhUv1",
			"expMonth" : "4",
			"expYear" : "2018",
			"brand" : "Visa",
			"type" : "Credit Card"
		},
		"captured" : true,
		"refunded" : false,
		"disputed" : true
	},
	"evidence" : {
		"productDescription" : "Exclusive black shoes",
		"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
	},
	"evidenceDetails" : {
		"hasEvidence" : true,
		"submissionCount" : 1
	}
}
				

List Disputes

List dispute 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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

Successful request returns list of a dispute object.

DEFINITION


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

EXAMPLE REQUEST


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

EXAMPLE RESPONSE


{
	"list": [{
		"id" : "disp_GOqyiOF9575FUYMZ73gjNrcY",
		"created" : 1489571590,
		"objectType" : "dispute",
		"updated" : 1489571590,
		"amount" : 1000,
		"currency" : "EUR",
		"status" : "CHARGEBACK_NEW",
		"reason" : "GENERAL",
		"acceptedAsLost" : false,
		"charge" : {
			"id" : "char_wPLWar517f4YeEhlLwxGs8u6",
			"created" : 1489571590,
			"objectType" : "charge",
			"amount" : 0,
			"currency" : "EUR",
			"card" : {
				"id" : "card_bF07BXcvdyPW4Mq6aW8lRK5l",
				"created" : 1489571590,
				"objectType" : "card",
				"first6" : "424200",
				"last4" : "0018",
				"fingerprint" : "k7766nfnZcWDhUv1",
				"expMonth" : "4",
				"expYear" : "2018",
				"brand" : "Visa",
				"type" : "Credit Card"
			},
			"captured" : true,
			"refunded" : false,
			"disputed" : true
		},
		"evidence" : {
			"productDescription" : "Exclusive black shoes",
			"customer_communication" : "file_2nayTQXBBjaVEPVtCwGCbqOj"
		},
		"evidenceDetails" : {
			"hasEvidence" : true,
			"submissionCount" : 1
		}
	}]
}
			

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.

File Upload object

Attributes

id
string
created
timestamp
objectType
string (value is always "file_upload")
purpose
string Purpose of this file object. Possible values are: dispute_evidence.
size
integer Size of uploaded file in bytes.
type
string Type of this file object. Possible values are: pdf, jpg, png.
url
string Read-only URL from which this file can be downloaded.

EXAMPLE RESPONSE


{
	"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
	"created" : 1415810511,
	"objectType" : "file_upload",
	"purpose" : "dispute_evidence",
	"size" : 28461,
	"type" : "jpg"
}
				

Create a File Upload

Creates a new file upload object.

Arguments

file
multipart file, required
purpose
string, required Purpose of this file object. Possible values are: dispute_evidence

Result

Successful request returns a file upload object that represents uploaded file.

DEFINITION


POST https://uploads.securionpay.com/files
				

EXAMPLE REQUEST


curl https://uploads.securionpay.com/files \
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \
    -F "purpose=dispute_evidence" \
    -F file="@example-file.jpg"
				

EXAMPLE RESPONSE


{
	"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
	"created" : 1415810511,
	"objectType" : "file_upload",
	"purpose" : "dispute_evidence",
	"size" : 28461,
	"type" : "jpg"
}
				

Retrieve an existing File Upload

Retrieve an existing file upload object.

Arguments

fileUploadId
string, required Identifier of file upload object that should be retrieved.

Result

Successful request returns a file upload object.

DEFINITION


GET https://uploads.securionpay.com/files/{FILE_UPLOAD_ID}
				

EXAMPLE REQUEST


curl https://uploads.securionpay.com/files/file_2nayTQXBBjaVEPVtCwGCbqOj
	-u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
				

EXAMPLE RESPONSE


{
	"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
	"created" : 1415810511,
	"objectType" : "file_upload",
	"purpose" : "dispute_evidence",
	"size" : 28461,
	"type" : "jpg"
}
				

List File Uploads

List file upload 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
purpose
string, optional Returns only file uploads with given purpose.
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.
includeTotalCount
boolean, optional (default is false) If specified then result will include total number of objects matched by provided filters.

Result

Successful request returns list of a file upload object.

DEFINITION


GET https://uploads.securionpay.com/files
				

EXAMPLE REQUEST


curl https://uploads.securionpay.com/files?includeTotalCount=true
				

EXAMPLE RESPONSE


{
	"totalCount": 1,
	"list": [{
		"id" : "file_2nayTQXBBjaVEPVtCwGCbqOj",
		"created" : 1415810511,
		"objectType" : "file_upload",
		"purpose" : "dispute_evidence",
		"size" : 28461,
		"type" : "jpg"
	}]
}