OpenAPI: https://integrations.yoursafe.com/openapi/direct.json

# Yoursafe Direct

- https://secure.yoursafedirect.com

## YoursafeDirect purchase

Create new purchase

    Example for [Verotel FlexPay PHP client library](https://github.com/verotel/flexpay-php-client):

```php
$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

    Example for [Verotel FlexPay Java client library](https://github.com/verotel/flexpay4j):

```java
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();
```

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

### HTTP request

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

<aside class="doc-callout doc-callout--success">
<p><a href="#success-postback">Success postback</a> is sent after approved order</p>
</aside>

`GET /status/order`

### Query parameters

- `version` (number, required)
  version of the FlexPay call, `4` for this version
- `shopID` (number, required)
  numerical ID of the website in the Verotel system
- `type` (string, required)
  `purchase` must be set
- `priceAmount` (number, required)
  amount to be processed in nnn.nn format
- `priceCurrency` (string, required)
  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
- `description` (string, required)
  description of the product. Text is displayed on the iDEAL payment page - max 100 printable characters
- `paymentMethod` (string, required)
  `IDEAL` must be set.
- `referenceID` (string)
  merchant’s reference identifier. It must be unique if provided
- `custom1` (string)
  pass-through variable - max 255 printable characters. Is returned in postbacks
- `custom2` (string)
  pass-through variable - max 255 printable characters. Is returned in postbacks
- `custom3` (string)
  pass-through variable - max 255 printable characters. Is returned in postbacks
- `successURL` (string)
  URL for redirect after successful transaction - max 255 characters. Can be omitted if default success landing URL is set on the website.
- `declineURL` (string)
  URL for redirect after declined transaction - max 255 characters. Can be omitted if default decline landing URL is set on the website.
- `mcc` (string)
  4-digit Merchant category code according to ISO 18245. Mandatory for CPSP transactions
- `subCreditorName` (string)
  1-35 char CPSP sub-merchant name. Mandatory for CPSP transactions
- `subCreditorId` (number)
  1-6 digit CPSP sub-merchant ID. Mandatory for CPSP transactions
- `subCreditorCountry` (string)
  2-char CPSP sub-merchant country code according to ISO 3166. Mandatory for CPSP transactions
- `email` (string, required)
  email of the buyer. NOTE: email is excluded from signature calculations (max 100 chars else it will be ignored)
- `signature` (string, required)
  Signature calculation

## Success postback

Verify postback data

        Example for [Verotel FlexPay PHP client library](https://github.com/verotel/flexpay-php-client)

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

        Verify postback data

        Example for [Verotel FlexPay Java client library](https://github.com/verotel/flexpay4j)

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

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.

<aside class="doc-callout doc-callout--notice">
<p>For Credit Card payments - If no such response is received, an automatic refund is initiated.</p>
</aside>

`GET`

Your endpoint receives this call.

### Query parameters

- `shopID` (number)
  numerical ID of the website in the Verotel system
- `type` (string)
  `purchase`
- `referenceID` (string)
  merchant reference identifier. It must be unique if provided
- `saleID` (number)
  identifier of the sale in the Verotel system
- `transactionID` (number)
  identifier of the transaction in the Verotel system
- `priceAmount` (number)
  amount to be processed in nnn.nn format
- `priceCurrency` (string)
  3 char ISO code of the Sale currency
- `custom1` (string)
  pass-through variable - max 255 printable characters
- `custom2` (string)
  pass-through variable - max 255 printable characters
- `custom3` (string)
  pass-through variable - max 255 printable characters
- `paymentMethod` (string)
  payment method, `IDEAL`
- `signature` (string)
  Signature calculation

## Status page request

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

```java
URL statusUrl = flexPayClient.getStatusUrlBySale(123456);
```

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

`GET /status/order`

### Query parameters

- `version` (number)
  `4`
- `shopID` (number)
  numerical ID of the website in the Verotel system
- `referenceID` (string)
  Merchant’s reference identifier if provided (referenceID OR saleID must be posted - NOT BOTH)
- `saleID` (number)
  Verotel saleID identifier (referenceID OR saleID must be posted - NOT BOTH)
- `signature` (string)
  Signature calculation

### Response

#### 200

- `response` (string)
  `FOUND` - purchase record found and returned
  `NOTFOUND` - purchase not found
  `ERROR` - error (see ‘error’ key)
- `error` (string)
  message (for response=`ERROR`)
- `saleID` (string)
  identifier of the transaction in Verotel System
- `shopID` (string)
  ID of website in Verotel system
- `paymentMethod` (string)
  an identifier of payment method that was used for the transaction.
- `priceAmount` (string)
  amount processed. in nnn.nn formatt
- `priceCurrency` (string)
  3 char ISO code of the Sale currency
- `description` (string)
  Product description text - max 100 printable characters
- `referenceID` (string)
  Merchant reference identifier - max 100 printable characters
- `name` (string)
  name of the buyer
- `email` (string)
  email address of the buyer
- `country` (string)
  selected or detected country ISO code (ISO 3166-1-alpha-2 code)
- `createdOn` (string)
  Timestamp of purchase creation
- `saleResult` (string)
  purchase processing result (APPROVED)

## Signature calculation

Calculate signature

    Example for [Verotel FlexPay PHP client library](https://github.com/verotel/flexpay-php-client)

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

    Calculate signature

    Example for [Verotel FlexPay Java client library](https://github.com/verotel/flexpay4j)

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

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.

### 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

```
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

```
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`