Yoursafe Direct

OpenAPI

Yoursafe Direct settles an iDEAL payment into a Yoursafe business account. Buyers pay on secure.yoursafedirect.com through the FlexPay purchase call, with paymentMethod set to IDEAL.

https://secure.yoursafedirect.com

YoursafeDirect purchase

Create new purchase

Example for Verotel FlexPay PHP client library:

Example for Verotel FlexPay Java client library:

FlexPay purchase initiates payment and redirects the buyer to the iDEAL payment page.

HTTP request

GET https://secure.yoursafedirect.com/status/order?

$flexpayClient = new Verotel\FlexPay\Client(
    685478,                   // shop ID / website ID
    "d6dToIj2d6YJ1PX2D1W9"    // FlexPay signatureKey
    new Verotel\FlexPay\YoursafeDirect()
);

$purchaseUrl = $flexpayClient->get_purchase_URL([
    "priceAmount"   => 14.00,
    "priceCurrency" => "EUR",
    "description"   => "Purchase of foo",
    "paymentMethod" => "IDEAL",
    "email"         => "example@example.com",
    "declineURL"    => "http://example.com/declined",
    "successURL"    => "http://example.com/success"
]);

    Create new purchase

FlexPayClient flexPayClient = new FlexPayClient(
    685478,                 // shop ID / website ID
    "d6dToIj2d6YJ1PX2D1W9", // FlexPay signatureKey
    Brand.YOURSAFE_DIRECT
);

URL purchaseUrl = flexPayClient.purchaseBuilder()
    .withAmount(BigDecimal.valueOf(14), SaleCurrency.EUR)
    .withDescription("Purchase of foo")
    .withPaymentMethod(PaymentMethod.IDEAL)
    .withEmail("example@example.com")
    .withDeclineURL("http://example.com/declined")
    .withSuccessURL("http://example.com/back")
    .build();

GET https://secure.yoursafedirect.com/status/order
    ?version=4
    &shopID=12345
    &type=purchase
    &priceAmount=9.99
    &priceCurrency=USD
    &description=Test purchase
    &paymentMethod=CC
    &referenceID=order-1001
    &custom1=xxyyzz
    &custom2=custom-2
    &custom3=custom-3
    &successURL=https://example.com/success
    &declineURL=https://example.com/declined
    &mcc=value
    &subCreditorName=value
    &subCreditorId=1
    &subCreditorCountry=value
    &email=buyer@example.com
    &signature=abcdef0123456789abcdef0123456789abcdef01

const url = new URL("https://secure.yoursafedirect.com/status/order");
url.searchParams.set("version", "4");
url.searchParams.set("shopID", "12345");
url.searchParams.set("type", "purchase");
url.searchParams.set("priceAmount", "9.99");
url.searchParams.set("priceCurrency", "USD");
url.searchParams.set("description", "Test purchase");
url.searchParams.set("paymentMethod", "CC");
url.searchParams.set("referenceID", "order-1001");
url.searchParams.set("custom1", "xxyyzz");
url.searchParams.set("custom2", "custom-2");
url.searchParams.set("custom3", "custom-3");
url.searchParams.set("successURL", "https://example.com/success");
url.searchParams.set("declineURL", "https://example.com/declined");
url.searchParams.set("mcc", "value");
url.searchParams.set("subCreditorName", "value");
url.searchParams.set("subCreditorId", "1");
url.searchParams.set("subCreditorCountry", "value");
url.searchParams.set("email", "buyer@example.com");
url.searchParams.set("signature", "abcdef0123456789abcdef0123456789abcdef01");
const response = await fetch(url);

from urllib.parse import urlencode
from urllib.request import urlopen

params = {
    "version": "4",
    "shopID": "12345",
    "type": "purchase",
    "priceAmount": "9.99",
    "priceCurrency": "USD",
    "description": "Test purchase",
    "paymentMethod": "CC",
    "referenceID": "order-1001",
    "custom1": "xxyyzz",
    "custom2": "custom-2",
    "custom3": "custom-3",
    "successURL": "https://example.com/success",
    "declineURL": "https://example.com/declined",
    "mcc": "value",
    "subCreditorName": "value",
    "subCreditorId": "1",
    "subCreditorCountry": "value",
    "email": "buyer@example.com",
    "signature": "abcdef0123456789abcdef0123456789abcdef01",
}
url = "https://secure.yoursafedirect.com/status/order?" + urlencode(params)
response = urlopen(url)

GET/status/order

Query parameters

versionnumberrequired

version of the FlexPay call, 4 for this version

shopIDnumberrequired

numerical ID of the website in the Verotel system

typestringrequired

purchase must be set

priceAmountnumberrequired

amount to be processed in nnn.nn format

priceCurrencystringrequired

3-char ISO code, must be one of the Sale currencies (USD EUR GBP AUD CAD CHF DKK NOK SEK), depending on your account setup

descriptionstringrequired

description of the product. Text is displayed on the iDEAL payment page - max 100 printable characters

paymentMethodstringrequired

IDEAL must be set.

referenceIDstring

merchant’s reference identifier. It must be unique if provided

custom1string

pass-through variable - max 255 printable characters. Is returned in postbacks

custom2string

pass-through variable - max 255 printable characters. Is returned in postbacks

custom3string

pass-through variable - max 255 printable characters. Is returned in postbacks

successURLstring

URL for redirect after successful transaction - max 255 characters. Can be omitted if default success landing URL is set on the website.

declineURLstring

URL for redirect after declined transaction - max 255 characters. Can be omitted if default decline landing URL is set on the website.

mccstring

4-digit Merchant category code according to ISO 18245. Mandatory for CPSP transactions

subCreditorNamestring

1-35 char CPSP sub-merchant name. Mandatory for CPSP transactions

subCreditorIdnumber

1-6 digit CPSP sub-merchant ID. Mandatory for CPSP transactions

subCreditorCountrystring

2-char CPSP sub-merchant country code according to ISO 3166. Mandatory for CPSP transactions

emailstringrequired

email of the buyer. NOTE: email is excluded from signature calculations (max 100 chars else it will be ignored)

signaturestringrequired

Signature calculation

Success postback

Verify postback data

Example for Verotel FlexPay PHP client library

Example for Verotel FlexPay Java client library

The successful sale postback is sent to the “Postback URL” immediately after the sale has been processed. The postback is sent only for successfully approved transactions. The data in the postback provide essential information about the sale. If more information is needed, the merchant should query the status page.

Important: The Verotel system expects HTTP status code 200 and plain text “OK” response. The response must be returned within 30 seconds.

// pass GET params received in postback
$paramsAreVerified = $flexPayClient->validate_signature([...]);

    Verify postback data

// pass GET params received in postback
Boolean paramsAreVerified = flexPayClient.validateSignature(Map.of(...));

GET https://example.com/postback
    ?shopID=12345
    &type=purchase
    &referenceID=order-1001
    &saleID=123456
    &transactionID=987654
    &priceAmount=9.99
    &priceCurrency=USD
    &custom1=xxyyzz
    &custom2=custom-2
    &custom3=custom-3
    &paymentMethod=CC
    &signature=abcdef0123456789abcdef0123456789abcdef01

const url = new URL("https://example.com/postback");
url.searchParams.set("shopID", "12345");
url.searchParams.set("type", "purchase");
url.searchParams.set("referenceID", "order-1001");
url.searchParams.set("saleID", "123456");
url.searchParams.set("transactionID", "987654");
url.searchParams.set("priceAmount", "9.99");
url.searchParams.set("priceCurrency", "USD");
url.searchParams.set("custom1", "xxyyzz");
url.searchParams.set("custom2", "custom-2");
url.searchParams.set("custom3", "custom-3");
url.searchParams.set("paymentMethod", "CC");
url.searchParams.set("signature", "abcdef0123456789abcdef0123456789abcdef01");
const response = await fetch(url);

from urllib.parse import urlencode
from urllib.request import urlopen

params = {
    "shopID": "12345",
    "type": "purchase",
    "referenceID": "order-1001",
    "saleID": "123456",
    "transactionID": "987654",
    "priceAmount": "9.99",
    "priceCurrency": "USD",
    "custom1": "xxyyzz",
    "custom2": "custom-2",
    "custom3": "custom-3",
    "paymentMethod": "CC",
    "signature": "abcdef0123456789abcdef0123456789abcdef01",
}
url = "https://example.com/postback?" + urlencode(params)
response = urlopen(url)

GETPostback

Your endpoint receives this call.

Query parameters

shopIDnumber

numerical ID of the website in the Verotel system

typestring

purchase

referenceIDstring

merchant reference identifier. It must be unique if provided

saleIDnumber

identifier of the sale in the Verotel system

transactionIDnumber

identifier of the transaction in the Verotel system

priceAmountnumber

amount to be processed in nnn.nn format

priceCurrencystring

3 char ISO code of the Sale currency

custom1string

pass-through variable - max 255 printable characters

custom2string

pass-through variable - max 255 printable characters

custom3string

pass-through variable - max 255 printable characters

paymentMethodstring

payment method, IDEAL

signaturestring

Signature calculation

Status page request

The status of a sale made with a FlexPay API can be reviewed by querying the status page. Status page provides complete information in - YAML format - about the sale, the buyer, and its status.

HTTP request

GET https://secure.yoursafedirect.com/status/order?

NOTFOUND - purchase not found ERROR - error (see ‘error’ key) |

$statusURL = $flexPayClient->get_status_URL(['saleID' => 123456]);

URL statusUrl = flexPayClient.getStatusUrlBySale(123456);

GET https://secure.yoursafedirect.com/status/order
    ?version=4
    &shopID=12345
    &referenceID=order-1001
    &saleID=123456
    &signature=abcdef0123456789abcdef0123456789abcdef01

const url = new URL("https://secure.yoursafedirect.com/status/order");
url.searchParams.set("version", "4");
url.searchParams.set("shopID", "12345");
url.searchParams.set("referenceID", "order-1001");
url.searchParams.set("saleID", "123456");
url.searchParams.set("signature", "abcdef0123456789abcdef0123456789abcdef01");
const response = await fetch(url);

from urllib.parse import urlencode
from urllib.request import urlopen

params = {
    "version": "4",
    "shopID": "12345",
    "referenceID": "order-1001",
    "saleID": "123456",
    "signature": "abcdef0123456789abcdef0123456789abcdef01",
}
url = "https://secure.yoursafedirect.com/status/order?" + urlencode(params)
response = urlopen(url)

GET/status/order

Query parameters

versionnumber

4

shopIDnumber

numerical ID of the website in the Verotel system

referenceIDstring

Merchant’s reference identifier if provided (referenceID OR saleID must be posted - NOT BOTH)

saleIDnumber

Verotel saleID identifier (referenceID OR saleID must be posted - NOT BOTH)

signaturestring

Signature calculation

Response

200

responsestring

FOUND - purchase record found and returned
NOTFOUND - purchase not found
ERROR - error (see ‘error’ key)

errorstring

message (for response=ERROR)

saleIDstring

identifier of the transaction in Verotel System

shopIDstring

ID of website in Verotel system

paymentMethodstring

an identifier of payment method that was used for the transaction.

priceAmountstring

amount processed. in nnn.nn formatt

priceCurrencystring

3 char ISO code of the Sale currency

descriptionstring

Product description text - max 100 printable characters

referenceIDstring

Merchant reference identifier - max 100 printable characters

namestring

name of the buyer

emailstring

email address of the buyer

countrystring

selected or detected country ISO code (ISO 3166-1-alpha-2 code)

createdOnstring

Timestamp of purchase creation

saleResultstring

purchase processing result (APPROVED)

Signature calculation

Calculate signature

Example for Verotel FlexPay PHP client library

Example for Verotel FlexPay Java client library

If you are using one of our client libraries, signature calculation is handled by the library.

The signature used in FlexPay requests and postbacks is calculated as a SHA-256 hash (hexadecimal output) from the request parameters.

The first parameter has to be your signatureKey, followed by the parameters ordered alphabetically by their names.

Optional arguments that are used (have value) must be contained in the signature calculation. Optional arguments that are not used must not be contained in the signature calculation.

The email parameter in “startorder” request is not included in the signature calculations.

It is mandatory to convert arguments values into UTF-8 before computing the signature.

$computed_signature = $flexpayClient->get_signature([
    'description' => 'Super video download',
    'priceAmount' => '9.99',
    'priceCurrency' => 'USD',
    'shopID' => 12345,
    'version' => 4,
]);

Calculate signature

String computedSignature = flexpayClient.getSignature(Map.of(
    "description", "Super video download",
    "priceAmount", "9.99",
    "priceCurrency", "USD",
    "shopID", 12345,
    "version", 4
));

Example calculation

Parameter	Value
(signatureKey)	BddJxtUBkDgFB9kj7Zwguxde4gAqha
description	Super video download
priceAmount	9.99
priceCurrency	USD
custom1	xxyyzz
shopID	64233
type	purchase
version	`4`

Signature calculation using the values above

Formula

signature = sha256_hex(BddJxtUBkDgFB9kj7Zwguxde4gAqha:custom1=xxyyzz:description=Super video download:priceAmount=9.99:priceCurrency=USD:shopID=64233:type=purchase:version=4) => ccaf2357fe330654322a1b0f3f92984b3fe2a1462d6fc5082650a00c5ada2f2a

The FlexPay purchase request then is

HTTP

https://secure.verotel.com/startorder?custom1=xxyyzz&description=Super+video+download&priceAmount=9.99&priceCurrency=USD&shopID=64233&type=purchase&version=4&signature=ccaf2357fe330654322a1b0f3f92984b3fe2a1462d6fc5082650a00c5ada2f2a

List of all signature parameters

This lists all parameters that must be part of the signature calculation - if they have non-empty value.

version
shopID
priceAmount
priceCurrency
description
referenceID
saleID
custom1
custom2
custom3
mcc
subCreditorName
subCreditorId
subCreditorCountry

HTTP request

Query parameters

Query parameters

HTTP request

Query parameters

Response

User management