Finexpay Api v1.0

Finexpay Api v1.0

Introduction

Finexpay API is a REST API. You can use HTTP requests to communicate with the API.


Sandbox url is : https://api-sandbox.finexpay.com/

Production url is : https://api.finexpay.com/

Authentication

To authenticate your API calls, you should first generate your API keys.

  1. If you don't have yet an account, you can simply create your account here.
  2. Copy your API key from here.

You will use this key in your request's Authorization header.

Header Value
Authorization fxp-key API_key

NOTE: API key provides full account access, you should keep it secure. If you think your API key is compromised, you can generate a new one here or use the second API key.

Errors

We expose API errors in two ways: standard HTTP response codes and human-readable messages in JSON format.

Error code Description
400 Bad request
401 Unauthorized - API key is invalid
404 Not Found -- The specified resource could not be found.
429 Too Many Requests
500 Internal Server Error

Error 400

This error occurred when there is a validation error. For example when a parameter is not well formatted or a mandatory parameter is missing.

Name type Description
error_code string equal to VALIDATION_ERROR
errors array list of validation errors
   property_name string invalid field name
   message string error description
   error_code string error code could be INVALID_VALUE,INVALID_FIELD_LENGTH ...

Error 401

This error suggests that your API key was missing from your request, or that something was formatted or named improperly in your header.

Error 404

The resource doesn’t exist. It’s possible there’s a typo in your request.

Error 429

You have sent too many requests in a given amount of time.

Error 500

Internal Server Error. We had a problem with our server. Try again later or contact our support.

Callback URLs

Webhooks

Webhooks are used by Fienxpay to notify Partner’s platform when specified events occurs. They are called with POST method, with a application/json content. All Webhooks content have the same structure with data whose structure depends on the Webhook type.

Webhook's structure is:

{
    "id": string,
    "type": string,
    "data": object
}

Transaction update

You will be notified on the configured server webhook url, each time one of the below events occurs on a Transaction:
1- Accepted: The Buyer accepted the Transaction.
2- Rejected: The Buyer is not eligible or has rejected the Transaction.
3- Expired: The Transaction was not accepted within the allowed Transaction timeout, or the Buyer profile could be not validated within the allowed Buyer validation timeout.
4- Canceled: The Transaction was canceled.
5- BuyerPendingValidation: The Buyer accepted the Transaction, but the Buyer profile is not yet validated.Once the Buyer profile is validated by Finexpay, you will be notified by this server webhook.If the Buyer profile cannnot be validated within the configured Buyer validation timeout, the Transaction will set as expired and you will be notified by this server webhook.
6- Paid: The Transaction was paid by the Buyer.
7- PaymentRejected: The Transaction payment was rejected by the Buyer.

Posted data structure for server webhook is:

{
    "id": string,
    "type": 'TransactionUpdated',
    "data":
    {
        "merchantId": string,
        "merchantTransactionNumber": string,
        "amount": number,
        "buyerId": string,
        "additionalData": string,
        "transactionId": string,
        "transactionStatus": TransactionStatus,
        "notificationType": NotificationType
    }
}

enum TransactionStatus
{
    Initiated = 1,
    Accepted,
    Rejected,
    Expired,
    Canceled,
    BuyerPendingValidation
}
enum NotificationType
{
    Accepted = 1,
    Rejected,
    Expired,
    Canceled,
    BuyerPendingValidation,
    Payed,
    PaymentRejected
}

Merchant payment generated

You will be notified on the configured server webhook url, when a payment is generated on each Merchant. Posted data structure for server webhook is:

{
    "id": string,
    "type": 'MerchantPayment',
    "data":
    {
        "id": string, // MerchandPaymentId
        "merchantId": string,
        "paymentDate": string,
        "amount": number, // Amount of the merchant payment
        "bankTransferLabel": string, // Label of the payment, as readable in bank statement
        "transactions": [ // List of the transactions financed in this payment
        {
            "amount": number,
            "merchantNumber": string,
            "id": string // Id of the transaction request
        }],
        "creditNotes": [ // List of credit notes definanced in this payment
        {
            "Amount": number, // Total amount of this credit note
            "TreatedAmount": number, // Amount definanced in this payment
            "MerchantNumber": string,
            "OriginalTransactionId": string // Id of the original transaction request of this credit note
        }]
    }
}


Please note that, usually, all transactions and credit notes of the day will be financed, but in some rare cases, credit notes could be partially definanced:
* Day 1: Buyer uses Finexpay to pay Transaction 1 (1000 €),
* Day 1 (end): Finexpay generates a payment to the merchant for 1000 €,
* Day 2: The same buyer does a transaction 2 for 200 €, and returns alf of the transaction 1, a credit note of 500 € is created,
* Day 2 (end): Finexpay calculates the amount of payment to the merchant : 200 - 500 = -300 €. Finexpay does not generate a payment, and send the following webhook:

{
    "id": some_id,
    "type": 'MerchantPayment',
    "data":
    {
        "id": some_id,
        "merchantId": some_id,
        "paymentDate": the_date,
        "amount": 0,
        "bankTransferLabel": null,
        "transactions": [
        {
            "amount": 200,
            "merchantNumber": Transaction 2,
            "id": some_id
        }],
        "creditNotes": [
        {
            "Amount": -500,
            "TreatedAmount": -200,
            "MerchantNumber": Credit Note 1,
            "OriginalTransactionId": some_id
        }]
    }
}

* Day 3: Buyer uses Finexpay for Transaction 3, of 400 €
* Day 3 (end): Finexpay calculates the amount of payment to the merchant : 400 - 300 (remaining amount of the previous credit note) = 100 €. Finexpay generates a payment, and send the following webhook:

{
    "id": some_id,
    "type": 'MerchantPayment',
    "data":
    {
        "id": some_id,
        "merchantId": some_id,
        "paymentDate": the_date,
        "amount": 100,
        "bankTransferLabel": some_string,
        "transactions": [
        {
            "amount": 400,
            "merchantNumber": Transaction 3,
            "id": some_id
        }],
        "creditNotes": [
        {
            "Amount": -500,
            "TreatedAmount": -300,
            "MerchantNumber": Credit Note 1,
            "OriginalTransactionId": some_id
        }]
    }
}

Client callback url

When the Buyer accepets or rejects a transaction, he will be redirected to the corresponding configured URL.
Posted data for client callback url is:

{
    "merchantId": string,
    "merchantTransactionNumber": string,
    "amount": number,
    "buyerId": string,
    "additionalData": string,
    "transactionId": string,
    "transactionStatus": TransactionStatus
}

enum TransactionStatus
{
    Initiated = 1,
    Accepted,
    Rejected,
    Expired,
    Canceled,
    BuyerPendingValidation
}

Merchant

Create a new Merchant

curl --location --request POST 'https://api-sandbox.finexpay.com/api/v1.0/merchant' \
--header 'Content-Type: application/json' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece' \
--data-raw '{
    "CompanyIdentifier": {
        "CountryCode": "FR",
        "Type": "SIREN",
        "Value": "788592889"
    },
    "InternalId": "your_internal_merchant_id",
    "Name": "Finexkap"
}'
import http.clientconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
payload = "{\"CompanyIdentifier\": {\"CountryCode\": \"FR\",\"Type\": \"SIREN\",\"Value\": \"788592889\"},\"InternalId\": \"your_internal_merchant_id\",\"Name\": \"Finexkap\"}"
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
}
conn.request("POST", "/api/v1.0/merchant", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"CompanyIdentifier\": {\"CountryCode\": \"FR\",\"Type\": \"SIREN\",\"Value\": \"788592889\" },\"InternalId\": \"your_internal_merchant_id\",\"Name\": \"Finexkap\"}");
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/merchant")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/merchant",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
  "data": JSON.stringify({"CompanyIdentifier":{"CountryCode":"FR","Type":"SIREN","Value":"788592889"},"InternalId":"your_internal_merchant_id","Name":"Finexkap"}),
};$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/merchant');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "CompanyIdentifier": {
        "CountryCode": "FR",
        "Type": "SIREN",
        "Value": "788592889"
    },
    "InternalId": "your_internal_merchant_id",
    "Name": "Finexkap"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
class HelloWorld {
    static void Main(string[] args) {
            var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/merchant");
            client.Timeout = -1;
            var request = new RestRequest(Method.POST);
            request.AddHeader("Content-Type", "application/json");
            request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
            request.AddParameter("application/json", "{\"CompanyIdentifier\": {\"CountryCode\": \"FR\",\"Type\": \"SIREN\",\"Value\": \"788592889\"},\"InternalId\": \"your_internal_merchant_id\",\"Name\":\"Finexkap\"}",  ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
    }
}
}

A Merchant is a company using the Partner’s platform to provide services or goods to Buyers.
A Merchant has to be onboarded in our system to use Finexpay.

HTTP Request

POST /api/v1.0/merchant

Request Body application/json - CreateMerchantRequest

Merchant information.

Name Type Description
CompanyIdentifier Object
   Type string The company identifier type. For example SIREN for French company.
   Value string The company identifier value.
   CountryCode string The company identifier ISO 3166-1 alpha-2 (or ISO 3166-2) country code.
InternalId string The merchant internal id.
Name string The merchant company name.

Responses

Code Description Schema
200 Returns the newly created Merchant id. CreateMerchantResponse
400 The request is not valid.
Other possible error codes :
MERCHANT_ALREADY_EXISTS : a Merchant with the same company identifier or internal id already exists.
CustomBadRequest
401 Unauthorized ProblemDetails

Update the Merchant IBAN

curl --location --request POST 'https://api-sandbox.finexpay.com/api/v1.0/merchant/iban' \
--header 'Content-Type: application/json' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece' \
--data-raw '{
    "Bic": "CEPAFRPP751",
    "Iban": "FR2110096000509415461723I60",
    "MerchantId": "bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce"
}'
import http.clientconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
payload = "{\"Bic\": \"CEPAFRPP751\",\"Iban\": \"FR2110096000509415461723I60\",\"MerchantId\": \"bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce\"}"
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
}
conn.request("POST", "/api/v1.0/merchant/iban", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"Bic\": \"CEPAFRPP751\",\"Iban\": \"FR2110096000509415461723I60\",\"MerchantId\": \"bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce\"}");
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/merchant/iban")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/merchant/iban",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
  "data": JSON.stringify({"Bic":"CEPAFRPP751","Iban":"FR2110096000509415461723I60","MerchantId":"bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce"}),
};$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/merchant/iban');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "Bic": "CEPAFRPP751",
    "Iban": "FR2110096000509415461723I60",
    "MerchantId": "bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
class HelloWorld {
    static void Main(string[] args) {
            var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/merchant/iban");
            client.Timeout = -1;
            var request = new RestRequest(Method.POST);
            request.AddHeader("Content-Type", "application/json");
            request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
            request.AddParameter("application/json", "{\"Bic\": \"CEPAFRPP751\",\"Iban\": \"FR2110096000509415461723I60\",\"MerchantId\": \"bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce\"}",  ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
    }
}
}

To finalize the Merchant in our system, you need to provide the bank details of the account on which the amount of the validated Transactions relating to the Merchant will be transferred by Finexpay.
The bank details may be provided through an upload of the IBAN document or by filling-out the details of the bank account.

HTTP Request

POST /api/v1.0/merchant/iban

Request Body application/json - UpdateMerchantIbanRequest

Merchant IBAN details

Name Type Description
MerchantId string The merchant id.
Iban string The merchant IBAN.
Bic string The merchant BIC.

Responses

Code Description Schema
200
400 The request is not valid.
Other possible error codes :
INVALID_IBAN
INVALID_BIC
MERCHANT_DO_NOT_EXISTS
CustomBadRequest
401 Unauthorized ProblemDetails

Upload the Merchant IBAN document

curl --location --request POST 'https://api-sandbox.finexpay.com/api/v1.0/merchant/iban-document' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece' \
--form 'Iban="Iban.pdf"' \
--form 'MerchantId="bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce"'
import http.client
import mimetypes
from codecs import encodeconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
dataList = []
boundary = 'wL36Yn8afVp8Ag7AmP8qZ0SA4n1v9T'
dataList.append(encode('--' + boundary))
dataList.append(encode('Content-Disposition: form-data; name=Iban; filename={0}'.format('Iban.pdf')))

fileType = mimetypes.guess_type('Iban.pdf')[0] or 'application/octet-stream'
dataList.append(encode('Content-Type: {}'.format(fileType)))
dataList.append(encode(''))

with open('Iban.pdf', 'rb') as f:
  dataList.append(f.read())
dataList.append(encode('--' + boundary))
dataList.append(encode('Content-Disposition: form-data; name=MerchantId;'))

dataList.append(encode('Content-Type: {}'.format('text/plain')))
dataList.append(encode(''))

dataList.append(encode("bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce"))
dataList.append(encode('--'+boundary+'--'))
dataList.append(encode(''))
body = b'\r\n'.join(dataList)
payload = body
headers = {
  'Content-Type': 'multipart/form-data',
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece',
  'Content-type': 'multipart/form-data; boundary={}'.format(boundary)
}
conn.request("POST", "/api/v1.0/merchant/iban-document", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("multipart/form-data");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
  .addFormDataPart("Iban","Iban.pdf",
    RequestBody.create(MediaType.parse("application/octet-stream"),new File("Iban.pdf")))
  .addFormDataPart("MerchantId","bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce")
  .build();
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/merchant/iban-document")
  .method("POST", body)
  .addHeader("Content-Type", "multipart/form-data")
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var form = new FormData();
form.append("Iban", fileInput.files[0], "Iban.pdf");
form.append("MerchantId", "bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce");var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/merchant/iban-document",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "multipart/form-data",
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/merchant/iban-document');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->addForm(array(
  'MerchantId' => 'bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce'
), array(
    array('name' => 'Iban', 'type' => '<Content-type header>', 'file' => 'Iban.pdf', 'data' => null)
));
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Content-Type' => 'multipart/form-data',
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
    class HelloWorld {
        static void Main(string[] args) {
            var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/merchant/iban-document");
            client.Timeout = -1;
            var request = new RestRequest(Method.POST);
            request.AddHeader("Content-Type", "multipart/form-data");
            request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
            request.AddFile("Iban", "Iban.pdf");
            request.AddParameter("MerchantId", "bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce");
            IRestResponse response = client.Execute(request);
            Console.WriteLine(response.Content);
        }
    }
}

The bank details may be provided through an upload of the IBAN document or by filling-out the details of the bank account.
Use this endpoint api to update the merchant IBAN using the iban document.

HTTP Request

POST /api/v1.0/merchant/iban-document

Request Body multipart/form-data

Name Type Format
MerchantId string uuid
Iban string binary

Responses

Code Description Schema
200
400 The request is not valid.
Other possible error codes :
INVALID_IBAN_DOCUMENT
MERCHANT_DO_NOT_EXISTS
CustomBadRequest
401 Unauthorized ProblemDetails

Get Merchant details by Finexpay identifier.

curl --location --request GET 'https://api-sandbox.finexpay.com/api/v1.0/merchant/bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
import http.clientconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
payload = ''
headers = {
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
}
conn.request("GET", "/api/v1.0/merchant/bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/merchant/bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce")
  .method("GET", null)
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/merchant/bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
};$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/merchant/bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce');
$request->setRequestMethod('GET');
$request->setOptions(array());
$request->setHeaders(array(
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
        class HelloWorld {
                static void Main(string[] args) {
                        var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/merchant/bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce");
                        client.Timeout = -1;
                        var request = new RestRequest(Method.GET);
                        request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
                        IRestResponse response = client.Execute(request);
                        Console.WriteLine(response.Content);
                }
        }
}

Get the Merchant details by Finexpay identifier, it is returned by Finexkap when Merchant was created.

HTTP Request

GET /api/v1.0/merchant/{id}

Parameters

Name Located in Description Required Type
id path Yes

Responses

Code Description Schema
200 MerchantDetails
400 The request is not valid.
Other possible error codes :
INVALID_MERCHANT_ID : no Merchant found with the given id
CustomBadRequest
401 Unauthorized ProblemDetails

Get Merchant details by internal identifier.

curl --location --request GET 'https://api-sandbox.finexpay.com/api/v1.0/merchant/internal-id/your_internal_merchant_id' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
import http.clientconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
payload = ''
headers = {
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
}
conn.request("GET", "/api/v1.0/merchant/internal-id/your_internal_merchant_id", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/merchant/internal-id/your_internal_merchant_id")
  .method("GET", null)
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/merchant/internal-id/your_internal_merchant_id",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
};$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/merchant/internal-id/your_internal_merchant_id');
$request->setRequestMethod('GET');
$request->setOptions(array());
$request->setHeaders(array(
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
        class HelloWorld {
                static void Main(string[] args) {
                        var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/merchant/internal-id/your_internal_merchant_id");
                        client.Timeout = -1;
                        var request = new RestRequest(Method.GET);
                        request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
                        IRestResponse response = client.Execute(request);
                        Console.WriteLine(response.Content);
                }
        }
}

Get the Merchant details by your internal identifier (passed as parameter when you created it).

HTTP Request

GET /api/v1.0/merchant/internal-id/{id}

Parameters

Name Located in Description Required Type
id path Yes

Responses

Code Description Schema
200 MerchantDetails
400 The request is not valid. CustomBadRequest
401 Unauthorized ProblemDetails

Get Merchant details by the company identifier.

curl --location --request GET 'https://api-sandbox.finexpay.com/api/v1.0/merchant/company-identifier?Type=SIREN&Value=788592889&CountryCode=FR' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
import http.clientconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
payload = ''
headers = {
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
}
conn.request("GET", "/api/v1.0/merchant/company-identifier?Type=SIREN&Value=788592889&CountryCode=FR", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/merchant/company-identifier?Type=SIREN&Value=788592889&CountryCode=FR")
  .method("GET", null)
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/merchant/company-identifier?Type=SIREN&Value=788592889&CountryCode=FR",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
};$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/merchant/company-identifier?Type=SIREN&Value=788592889&CountryCode=FR');
$request->setRequestMethod('GET');
$request->setOptions(array());
$request->setHeaders(array(
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
        class HelloWorld {
                static void Main(string[] args) {
                        var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/merchant/company-identifier?Type=SIREN&Value=788592889&CountryCode=FR");
                        client.Timeout = -1;
                        var request = new RestRequest(Method.GET);
                        request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
                        IRestResponse response = client.Execute(request);
                        Console.WriteLine(response.Content);
                }
        }
}

Get the Merchant details by the company identifier (country code, identifier type and identifier value).

HTTP Request

GET /api/v1.0/merchant/company-identifier

Parameters

Name Located in Description Required Type
Type query Yes
Value query Yes
CountryCode query Yes

Responses

Code Description Schema
200 MerchantDetails
400 The request is not valid.
CustomBadRequest
401 Unauthorized ProblemDetails

Settings

Update the Partner IBAN

curl --location --request POST 'https://api-sandbox.finexpay.com/api/v1.0/settings/iban' \
--header 'Content-Type: application/json' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece' \
--data-raw '{
    "Bic": "CEPAFRPP751",
    "Iban": "FR2110096000509415461723I60"
}'
import http.clientconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
payload = "{\"Bic\": \"CEPAFRPP751\",\"Iban\": \"FR2110096000509415461723I60\"}"
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
}
conn.request("POST", "/api/v1.0/settings/iban", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"Bic\": \"CEPAFRPP751\",\"Iban\": \"FR2110096000509415461723I60\"}");
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/settings/iban")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/settings/iban",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
  "data": JSON.stringify({"Bic":"CEPAFRPP751","Iban":"FR2110096000509415461723I60"}),
};$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/settings/iban');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "Bic": "CEPAFRPP751",
    "Iban": "FR2110096000509415461723I60"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
        class HelloWorld {
                static void Main(string[] args) {
                        var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/settings/iban");
                        client.Timeout = -1;
                        var request = new RestRequest(Method.POST);
                        request.AddHeader("Content-Type", "application/json");
                        request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
                        request.AddParameter("application/json", "{\"Bic\": \"CEPAFRPP751\",\"Iban\": \"FR2110096000509415461723I60\"}",  ParameterType.RequestBody);
                        IRestResponse response = client.Execute(request);
                        Console.WriteLine(response.Content);
                }
        }
}

If you want to set an IBAN at the Partner level, this is where you provide the Partner's bank details. The bank details may be provided through an upload of the IBAN document or by filling-out the details of the bank account.
This method is to upload an IBAN document, we will get IBAN details by OCR.

HTTP Request

POST /api/v1.0/settings/iban

Request Body application/json - UpdatePartnerIbanRequest

iban details.

Name Type Description
Iban string The Partner IBAN.
Bic string The Partner BIC.

Responses

Code Description Schema
200
400 The request is not valid.
Other possible error codes :
INVALID_IBAN
INVALID_BIC
CustomBadRequest
401 Unauthorized ProblemDetails

Upload the Partner IBAN document

curl --location --request POST 'https://api-sandbox.finexpay.com/api/v1.0/settings/iban-document' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece' \
--form 'Iban="Iban.pdf"'
import http.client
import mimetypes
from codecs import encodeconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
dataList = []
boundary = 'wL36Yn8afVp8Ag7AmP8qZ0SA4n1v9T'
dataList.append(encode('--' + boundary))
dataList.append(encode('Content-Disposition: form-data; name=Iban; filename={0}'.format('Iban.pdf')))

fileType = mimetypes.guess_type('Iban.pdf')[0] or 'application/octet-stream'
dataList.append(encode('Content-Type: {}'.format(fileType)))
dataList.append(encode(''))

with open('Iban.pdf', 'rb') as f:
  dataList.append(f.read())
dataList.append(encode('--'+boundary+'--'))
dataList.append(encode(''))
body = b'\r\n'.join(dataList)
payload = body
headers = {
  'Content-Type': 'multipart/form-data',
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece',
  'Content-type': 'multipart/form-data; boundary={}'.format(boundary)
}
conn.request("POST", "/api/v1.0/settings/iban-document", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("multipart/form-data");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
  .addFormDataPart("Iban","Iban.pdf",
    RequestBody.create(MediaType.parse("application/octet-stream"),
    new File("Iban.pdf")))
  .build();
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/settings/iban-document")
  .method("POST", body)
  .addHeader("Content-Type", "multipart/form-data")
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var form = new FormData();
form.append("Iban", fileInput.files[0], "Iban.pdf");var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/settings/iban-document",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "multipart/form-data",
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/settings/iban-document');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->addForm(array(), array(
    array('name' => 'Iban', 'type' => '<Content-type header>', 'file' => 'Iban.pdf', 'data' => null)
));
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Content-Type' => 'multipart/form-data',
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

using System;
using RestSharp;
namespace HelloWorldApplication {
        class HelloWorld {
                static void Main(string[] args) {
                        var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/settings/iban-document");
                        client.Timeout = -1;
                        var request = new RestRequest(Method.POST);
                        request.AddHeader("Content-Type", "multipart/form-data");
                        request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
                        request.AddFile("Iban", "Iban.pdf");
                        IRestResponse response = client.Execute(request);
                        Console.WriteLine(response.Content);
                }
        }
}

HTTP Request

POST /api/v1.0/settings/iban-document

Request Body multipart/form-data

Name Type Format
Iban string binary

Responses

Code Description Schema
200
400 The request is not valid.
Other possible error codes :
INVALID_IBAN : IBAN has an invalid structure.
INVALID_FIELD_LENGTH : The file length exceeded the maximum authorized file size of 4mb.
CustomBadRequest
401 Unauthorized ProblemDetails

Transaction

Initiate a new Transaction payment session

curl --location --request POST 'https://api-sandbox.finexpay.com/api/v1.0/transaction' \
--header 'Content-Type: application/json' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece' \
--data-raw '{
    "Amount": "1000",
    "DeclineCallbackUrl": "https://www.decline_url.com/",
    "MerchantId": "bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce",
    "MerchantTransactionNumber": "FCT123456",
    "ServerWebHookUrl": "https://www.server_webhook.com/",
    "SuccessCallbackUrl": "https://www.success_callback_url.com/",    
    "Language": "FR",
    "Timeout\": "00:30:00"
}'
import http.clientconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
payload = "{\"Amount\": \"1000\",\"DeclineCallbackUrl\": \"https://www.decline_url.com/\",\"MerchantId\": \"bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce\",\"MerchantTransactionNumber\": \"FCT123456\",\"ServerWebHookUrl\": \"https://www.server_webhook.com/\",\"SuccessCallbackUrl\": \"https://www.success_callback_url.com/\",    \"Language\": \"FR\",\"Timeout\": \"00:30:00\"}"
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
}
conn.request("POST", "/api/v1.0/transaction", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"Amount\": \"1000\",\"DeclineCallbackUrl\": \"https://www.decline_url.com/\",\"MerchantId\": \"bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce\",\"MerchantTransactionNumber\": \"FCT123456\",\"ServerWebHookUrl\": \"https://www.server_webhook.com/\",\"SuccessCallbackUrl\": \"https://www.success_callback_url.com/\",    \"Language\": \"FR\",\"Timeout\": \"00:30:00\"}");
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/transaction")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/transaction",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
  "data": JSON.stringify({"Amount":"1000","DeclineCallbackUrl":"https://www.decline_url.com/","MerchantId":"bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce","MerchantTransactionNumber":"FCT123456","ServerWebHookUrl":"https://www.server_webhook.com/","SuccessCallbackUrl":"https://www.success_callback_url.com/","Language":"FR","Timeout": "00:30:00"}),
};$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/transaction');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "Amount": "1000",
    "DeclineCallbackUrl": "https://www.decline_url.com/",
    "MerchantId": "bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce",
    "MerchantTransactionNumber": "FCT123456",
    "ServerWebHookUrl": "https://www.server_webhook.com/",
    "SuccessCallbackUrl": "https://www.success_callback_url.com/",    
    "Language": "FR",
    "Timeout": "00:30:00"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
        class HelloWorld {
                static void Main(string[] args) {
                        var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/transaction");
                        client.Timeout = -1;
                        var request = new RestRequest(Method.POST);
                        request.AddHeader("Content-Type", "application/json");
                        request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
                        request.AddParameter("application/json", "{\"Amount\": \"1000\",\"DeclineCallbackUrl\": \"https://www.decline_url.com/\",\"MerchantId\": \"bcb446d9-d80c-4e1d-b67c-dbb1b8cfb7ce\",\"MerchantTransactionNumber\": \"FCT123456\",\"ServerWebHookUrl\": \"https://www.server_webhook.com/\",\"SuccessCallbackUrl\": \"https://www.success_callback_url.com/\",    \"Language\": \"FR\",\"Timeout\": \"00:30:00\"}",  ParameterType.RequestBody);
                        IRestResponse response = client.Execute(request);
                        Console.WriteLine(response.Content);
                }
        }
}

When you display a payment button Finexpay on your platform and the Buyer clicks on it, you must first create a Transaction that must include at least the mandatory information required to identify the order and the Merchant (the optional information is specifically identified as such in the Transaction API documentation).

HTTP Request

POST /api/v1.0/transaction

Request Body application/json - InitiateTransactionRequest

Payment information

Name Type Description
MerchantId string The Merchant identifier
MerchantTransactionNumber string The Merchant Transaction number
Amount number The Transaction amount
SuccessCallbackUrl string The callback url to which the Buyer will be redirected if the Transaction was successfully completed. If this field is null or empty, then the callback set at the global setting will be used.
DeclineCallbackUrl string The callback url to which the Buyer will be redirected if it declined the Transaction or Finexpay refused the Transaction. If this field is null or empty, then the callback set at the global setting will be used.
ServerWebHookUrl string Server to server notification url. If this field is null or empty, then the webhook set at the global setting will be used.
BuyerId string The Buyer identifier, optional.
Language string Language of communication with the buyer (for now only French is supported).
AdditionalData string Additional information sent by Merchant, optional
Timeout string The Buyer has to accept or refuse the Transaction within this timeout. If this field is null, then the timeout set at the global setting will be used. For example 00:30:00 for 30 minutes, 1.00:20:00 for 1 day and 20 minutes as timeout.

Responses

Code Description Schema
200 Success InitiateTransactionResponse
400 The request is not valid.
Other possible error codes :
INVALID_MERCHANT_ID
INVALID_MERCHANT_TRANSACTION_NUMBER
INVALID_TRANSACTION_AMOUNT
MERCHANT_TRANSACTION_NUMBER_ALREADY_EXISTS : a Transaction with the same Merchant number was already accepted.
MERCHANT_NOT_FOUND : no Merchant found with the given id. INVALID_SETTINGS : callback urls are not configured.
CustomBadRequest

Cancel a Transaction

curl --location --request POST 'https://api-sandbox.finexpay.com/api/v1.0/transaction/cancel?transactionId=2e0b531c-e694-4a2e-94ca-e9d77b75f96a' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
import http.clientconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
payload = ''
headers = {
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
}
conn.request("POST", "/api/v1.0/transaction/cancel?transactionId=2e0b531c-e694-4a2e-94ca-e9d77b75f96a", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/transaction/cancel?transactionId=2e0b531c-e694-4a2e-94ca-e9d77b75f96a")
  .method("POST", body)
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/transaction/cancel?transactionId=2e0b531c-e694-4a2e-94ca-e9d77b75f96a",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
};$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/transaction/cancel?transactionId=2e0b531c-e694-4a2e-94ca-e9d77b75f96a');
$request->setRequestMethod('POST');
$request->setOptions(array());
$request->setHeaders(array(
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
        class HelloWorld {
                static void Main(string[] args) {
                        var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/transaction/cancel?transactionId=2e0b531c-e694-4a2e-94ca-e9d77b75f96a");
                        client.Timeout = -1;
                        var request = new RestRequest(Method.POST);
                        request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
                        IRestResponse response = client.Execute(request);
                        Console.WriteLine(response.Content);
                }
        }
}

Before the order is financed (so, when it's Initiated or BuyerPendingValidation), you may need to cancel it. In order to manage these operations you can cancel the Transaction.

HTTP Request

POST /api/v1.0/transaction/cancel

Parameters

Name Located in Description Required Type
transactionId query The transaction id. Yes

Responses

Code Description Schema
200
400 The request is not valid.
Other possible error codes :
TRANSACTION_NOT_FOUND
INVALID_OPERATION : Transaction can not be cancelled.

Add a credit note to an existing Transaction

curl --location --request POST 'https://api-sandbox.finexpay.com/api/v1.0/transaction/credit-note' \
--header 'Content-Type: application/json' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece' \
--data-raw '{
    "Amount": "200",
    "Date": "2020-12-24T10:41:43.623963",
    "TransactionId": "2e0b531c-e694-4a2e-94ca-e9d77b75f96a",
    "Comment": "return merchandise"
}'
import http.clientconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
payload = "{\"Amount\": \"200\",\"Date\": \"2020-12-24T10:41:43.623963\",\"TransactionId\": \"2e0b531c-e694-4a2e-94ca-e9d77b75f96a\",\"Comment\": \"return merchandise\"}"
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
}
conn.request("POST", "/api/v1.0/transaction/credit-note", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"Amount\": \"200\",\"Date\": \"2020-12-24T10:41:43.623963\",\"TransactionId\": \"2e0b531c-e694-4a2e-94ca-e9d77b75f96a\",\"Comment\": \"return merchandise\"}");
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/transaction/credit-note")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/transaction/credit-note",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
  "data": JSON.stringify({"Amount":"200","Date":"2020-12-24T10:41:43.623963","TransactionId":"2e0b531c-e694-4a2e-94ca-e9d77b75f96a","Comment":"return merchandise"}),
};$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/transaction/credit-note');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "Amount": "200",
    "Date": "2020-12-24T10:41:43.623963",
    "TransactionId": "2e0b531c-e694-4a2e-94ca-e9d77b75f96a",
    "Comment": "return merchandise"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
        class HelloWorld {
                static void Main(string[] args) {
                        var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/transaction/credit-note");
                        client.Timeout = -1;
                        var request = new RestRequest(Method.POST);
                        request.AddHeader("Content-Type", "application/json");
                        request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
                        request.AddParameter("application/json", "{\"Amount\": \"200\",\"Date\": \"2020-12-24T10:41:43.623963\",\"TransactionId\": \"2e0b531c-e694-4a2e-94ca-e9d77b75f96a\",\"Comment\": \"return merchandise\"}",  ParameterType.RequestBody);
                        IRestResponse response = client.Execute(request);
                        Console.WriteLine(response.Content);
                }
        }
}

In the lifespan of an order, you may need to grant a credit note to your Buyer. In order to manage these operations you can reduce the amount of the related Transaction during its lifespan. This operation can be done only the order is financed, this operation will fail if the transaction is in Initiated or BuyerPendingValidation.

HTTP Request

POST /api/v1.0/transaction/credit-note

Request Body application/json - AddCreditNoteRequest

Name Type Description
TransactionId string The transaction id.
Amount number The credit note amount.
Date string The credit note date.
MerchantCreditNoteNumber string The Merchant credit note number
Comment string

Responses

Code Description Schema
200
400 The request is not valid.
Other possible error codes :
TRANSACTION_NOT_FOUND
INVALID_OPERATION : can not add credit note on Transaction with this status.
INVALID_AMOUNT

Get the Transaction details

curl --location --request GET 'https://api-sandbox.finexpay.com/api/v1.0/transaction/2e0b531c-e694-4a2e-94ca-e9d77b75f96a' \
--header 'Authorization: fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
import http.clientconn = http.client.HTTPSConnection("api-sandbox.finexpay.com")
payload = ''
headers = {
  'Authorization': 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
}
conn.request("GET", "/api/v1.0/transaction/2e0b531c-e694-4a2e-94ca-e9d77b75f96a", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api-sandbox.finexpay.com/api/v1.0/transaction/2e0b531c-e694-4a2e-94ca-e9d77b75f96a")
  .method("GET", null)
  .addHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "https://api-sandbox.finexpay.com/api/v1.0/transaction/2e0b531c-e694-4a2e-94ca-e9d77b75f96a",
  "method": "GET",
  "timeout": 0,
  "headers": {
    "Authorization": "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece"
  },
};$.ajax(settings).done(function (response) {
  console.log(response);
});
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-sandbox.finexpay.com/api/v1.0/transaction/2e0b531c-e694-4a2e-94ca-e9d77b75f96a');
$request->setRequestMethod('GET');
$request->setOptions(array());
$request->setHeaders(array(
  'Authorization' => 'fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
using System;
using RestSharp;
namespace HelloWorldApplication {
        class HelloWorld {
                static void Main(string[] args) {
                        var client = new RestClient("https://api-sandbox.finexpay.com/api/v1.0/transaction/2e0b531c-e694-4a2e-94ca-e9d77b75f96a");
                        client.Timeout = -1;
                        var request = new RestRequest(Method.GET);
                        request.AddHeader("Authorization", "fxp-key fxp_test_663d27aca67245b6bf9c1b2a27fecece");
                        IRestResponse response = client.Execute(request);
                        Console.WriteLine(response.Content);
                }
        }
}

HTTP Request

GET /api/v1.0/transaction/{id}

Parameters

Name Located in Description Required Type
id path Transaction id Yes

Responses

Code Description Schema
200 TransactionDetail
400 The request is not valid.
Other possible error codes :
TRANSACTION_NOT_FOUND

Schemas

CompanyIdentifier

Name Type Description
Type string The company identifier type. For example SIREN for French company.
Value string The company identifier value.
CountryCode string The company identifier ISO 3166-1 alpha-2 (or ISO 3166-2) country code.

CreateMerchantRequest

Name Type Description
CompanyIdentifier Object
   Type string The company identifier type. For example SIREN for French company.
   Value string The company identifier value.
   CountryCode string The company identifier ISO 3166-1 alpha-2 (or ISO 3166-2) country code.
InternalId string The merchant internal id.
Name string The merchant company name.

CreateMerchantResponse

Name Type Description
MerchantId string The newly created merchant id. Can be used later to initiate payment for this merchant.

ValidationError

Name Type Description
PropertyName string
ErrorMessage string
AttemptedValue
ErrorCode string

CustomBadRequest

Name Type Description
ErrorCode string
Errors array

ProblemDetails

Name Type Description
Type string
Title string
Status integer
Detail string
Instance string
Extensions object

UpdateMerchantIbanRequest

Name Type Description
MerchantId string The merchant id.
Iban string The merchant IBAN.
Bic string The merchant BIC.

MerchantIban

Name Type Description
Iban string The merchant iban.
BIC string The merchant bic.

MerchantDetails

Name Type Description
Id string The merchant Finexpay Id.
CompanyIdentifier Object
   Type string The company identifier type. For example SIREN for French company.
   Value string The company identifier value.
   CountryCode string The company identifier ISO 3166-1 alpha-2 (or ISO 3166-2) country code.
InternalId string The merchant internal id.
Name string The merchant company name.
CreationDate string The merchant creation date.
BankAccount Object
   Iban string The merchant iban.
   BIC string The merchant bic.

UpdatePartnerIbanRequest

Name Type Description
Iban string The Partner IBAN.
Bic string The Partner BIC.

InitiateTransactionRequest

Name Type Description
MerchantId string The Merchant identifier
MerchantTransactionNumber string The Merchant Transaction number
Amount number The Transaction amount
SuccessCallbackUrl string The callback url to which the Buyer will be redirected if the Transaction was successfully completed. If this field is null or empty, then the callback set at the global setting will be used.
DeclineCallbackUrl string The callback url to which the Buyer will be redirected if it declined the Transaction or Finexpay refused the Transaction. If this field is null or empty, then the callback set at the global setting will be used.
ServerWebHookUrl string Server to server notification url. If this field is null or empty, then the webhook set at the global setting will be used.
BuyerId string The Buyer identifier, optional.
Language string Language of communication with the buyer (for now only French is supported).
AdditionalData string Additional information sent by Merchant, optional
Timeout string The Buyer has to accept or refuse the Transaction within this timeout. If this field is null, then the timeout set at the global setting will be used. For example 00:30:00 for 30 minutes, 1.00:20:00 for 1 day and 20 minutes as timeout.

InitiateTransactionResponse

Name Type Description
Url string The url to which buyer should be redirect to perform the transaction payment.
RequestId string The payment request identifier.

AddCreditNoteRequest

Name Type Description
TransactionId string The transaction id.
Amount number The credit note amount.
Date string The credit note date.
MerchantCreditNoteNumber string The Merchant credit note number
Comment string

TransactionRequestStatus

Name
Initiated
Accepted
Rejected
Expired
Canceled
BuyerPendingValidation

TransactionDetail

Name Type Description
Id string Finexpay transaction id.
BuyerId string Finexpay buyer id.
MerchantId string Finexpay merchant id.
RequestDate string Transaction request date.
Date string Transaction funding date.
Amount number Transaction amount.
ProductId string Product id. Product contains sales loan configuration as pricing and duration.
Status Object
   Initiated
   Accepted
   Rejected
   Expired
   Canceled
   BuyerPendingValidation
MerchantPaymentDate string Merchant payment date.
SuccessCallbackUrl string The callback url to which the Buyer will be redirected if Transaction was successfully completed.
DeclineCallbackUrl string The callback url to which the Buyer will be redirected if it declined the Transaction or Finexpay refused the Transaction.
ServerWebHookUrl string Server to server notification url.
AdditionalData string Additional information sent by Merchant, optional