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.

    Webhooks

    Finexpay uses webhooks to notify the Partner’s platform when specific events occur. You will receive the webhooks notification with POST method and anapplication/json content. All webhooks share the same overall structure yet the data structure may vary according to the webhook type.

    A standard webhook structure is as below:

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

    Transaction update

    You will be directly notified on the configured server webhook url every time one of the events listed below happens of a specific Transaction:

    • Accepted: the Buyer accepted the Transaction.
    • Rejected: the Buyer is not eligible or has rejected the Transaction.
    • Expired: the Transaction was not accepted within the allowed Transaction validation timeout, or the Buyer profile could be not validated within the allowed Buyer validation timeout.
    • Canceled: the Transaction was canceled.
    • BuyerPendingValidation: the Buyer has accepted the Transaction, but the Buyer profile is not yet validated. Once the Buyer profile is validated by Finexpay, you will be notified by the server webhook. In case the Buyer profile cannot be validated within the configured Buyer validation timeout, the Transaction will be set as expired and you will be notified by the server webhook.
    • Paid: the Transaction was paid by the Buyer.
    • PaymentRejected: the Transaction payment was rejected by the Buyer.

    Posted data structure for server webhook is as below:

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

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

    {
        "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 the bank statement
            "transactions": [ // List of the transactions financed related to this payment
            {
                "amount": number,
                "merchantNumber": string,
                "id": string // Id of the transaction request
            }],
            "creditNotes": [ // List of credit notes definanced related to this payment
            {
                "Amount": number, // Total amount of this credit note
                "TreatedAmount": number, // Amount definanced related to this payment
                "MerchantNumber": string,
                "OriginalTransactionId": string // Id of the original transaction request for this credit note
            }]
        }
    }


    Please note that all transactions and credit notes are usually financed on the same date, however, in some rare instances, credit notes could be partially definanced as shown in the example below:

    • Day 1: a Buyer uses Finexpay to pay a Transaction 1 (1000 €),
    • Day 1 (end): Finexpay generates a payment to the Merchant for 1000 €,
    • Day 2: a Buyer does a Transaction 2 for 200 €, and then returns half of the Transaction 1. A credit note of 500 € is created,
    • Day 2 (end): Finexpay computes the amount of payment to the Merchant : 200 € - 500 € = -300 €. As the result is negative, Finexpay does not generate a payment, and sends 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: a Buyer uses Finexpay for a Transaction 3 (400 €)
    • Day 3 (end): Finexpay computes the amount of payment to the Merchant : 400 € - 300 € (remaining amount of the previous credit note) = 100 €. Finexpay then generates a payment and sends 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 accepts or rejects a transaction, he will be redirected to the corresponding configured URL. When the buyer accepted the transaction, it will be redirected to value of SuccessCallbackUrl given in Initiate a new Transaction payment session if available, otherwise the default value set in your dashboard is used. When the buyer declined the transaction, it will be redirected to value of DeclineCallbackUrl given in Initiate a new Transaction payment session if available, otherwise the default value set in your dashboard is used.
    The callback is called with a POST method, posted data is:

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

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

    Buyer

    Retrieve buyer by id.

    HTTP Request

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

    Parameters

    Name Located in Description Required Type
    id path The buyer id. Yes

    Responses

    Code Description Schema
    200 BuyerDetails
    400
    • BUYER_DOES_NOT_EXIST : The buyer does not exist.
    CustomBadRequest
    401 ProblemDetails

    Retrieve buyer by company identifier.

    HTTP Request

    GET /api/v1.0/buyer/by-company-identifier

    Parameters

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

    Responses

    Code Description Schema
    200 BuyerDetails
    400
    • BUYER_DOES_NOT_EXIST : The buyer does not exist.
    CustomBadRequest
    401 ProblemDetails

    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

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

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

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

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

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

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

    Payment

    Initiate a new payment session.

    When you display a payment button Finexpay on your platform and the Buyer clicks on it, you must first create a payment which contains a lis of Transactions containing at minimum the information of the order and of the Merchant, and will return a link to redirect the Buyer on Finexpay (see workflow).

    HTTP Request

    POST /api/v1.0/payment

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

    Request Body application/json - InitiatePaymentRequest

    Payment information

    Name Type Description
    TotalAmount number The payment total amount.
    SuccessCallbackUrl string The callback url to which the Buyer will be redirected if the Payment 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 Payment 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).
    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.
    AdditionalData string Additional information, optional
    TransactionRequests array Payment session transaction requests list.

    Responses

    Code Description Schema
    200 InitiatePaymentResponse
    400
    • TRANSACTION_REQUEST_LIST_CAN_NOT_BE_EMPTY : Transactions list is null or empty.
    • INVALID_SETTINGS: This error code is sent when server webhook or client callbacks url are not configured on the global configuration and not set in the request.
    • TOTAL_PAYMENT_AMOUNT_DIFFERENT_THAN_TOTAL_TRANSACTIONS_AMOUNT
    • BUYER_NOT_FOUND
    • MERCHANT_DO_NOT_EXISTS
    • MERCHANT_TRANSACTION_NUMBER_ALREADY_EXISTS: A transaction with the same merchant number was already financed.
    • DUPLICATED_TRANSACTIONS: Duplicated transaction found on the payment session.
    CustomBadRequest
    401 ProblemDetails

    Initiate a new payment session with no ui.

    Use this api endpoint to initiate a new payment session with no redirection to Finexpay prebuilt checkout page. When you use this api endpoint, we consider that the buyer automatically accept the payment. This operation is allowed only if the buyer has signed a contract where he agreed to accept all the payment you initiated on his behalf.

    HTTP Request

    POST /api/v1.0/payment/no-ui

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

    Request Body application/json - InitiateBuyerAutoAcceptedPaymentRequest

    Payment information

    Name Type Description
    TotalAmount number The payment total amount.
    BuyerId string The Buyer identifier.
    ProductId string The Product identifier.
    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.
    AdditionalData string Additional information, optional
    TransactionRequests array Payment session transaction requests list.

    Responses

    Code Description Schema
    200 InitiateBuyerAutoAcceptedPaymentResponse
    400
    • INVALID_SETTINGS : Your current configuration does not allow you to initiate payments without GUI. Or server webhook url is not configured on the global configuration and not set in the request.
    • BUYER_NOT_FOUND : The buyer does not exist.
    • PRODUCT_NOT_FOUND : Invalid product Id.
    • BUYER_CONTRACT_IS_NOT_SIGNED : The buyer contract is not signed.
    • INELIGIBLE_PAYMENT : The payment is ineligible.
    CustomBadRequest
    401 ProblemDetails

    Cancel a payment session.

    Payment session can be canceled only if no transaction was yet validated.

    HTTP Request

    POST /api/v1.0/payment/cancel

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

    Request Body application/json - CancelPaymentRequest

    The payment session id.

    Name Type Description
    PaymentId string The payment session id.

    Responses

    Code Description Schema
    200
    400
    • PAYMENT_NOT_EXISTS : The payment does not exist.
    • PAYMENT_IS_ALREADY_CANCELED : the payment is already canceled.
    • INVALID_PAYMENT_STATUS : Invalid payment status.
    • PAYMENT_HAS_VALIDATED_TRANSACTION : The payment has a validated transactions.
    ProblemDetails
    401 ProblemDetails

    Payout

    HTTP Request

    GET /api/v1.0/payout/bank-transfer-label/{bankTransferLabel}

    Parameters

    Name Located in Description Required Type
    bankTransferLabel path The bank transfer label Yes

    Responses

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

    Retrieve the transaction payout detail if exists.

    HTTP Request

    GET /api/v1.0/payout/transaction/{transactionId}

    Parameters

    Name Located in Description Required Type
    transactionId path The transaction id Yes

    Responses

    Code Description Schema
    200 PayoutDetail
    400 The request is not valid. CustomBadRequest
    401 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

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

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

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

    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 ProblemDetails

    Transaction

    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
    Idempotency-Key header Idempotency key

    Request Body application/json - CancelTransactionRequest

    request containing the transaction request id.

    Name Type Description
    TransactionRequestId string The transaction request id.

    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.
    CustomBadRequest
    401 Unauthorized ProblemDetails

    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

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

    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
    CustomBadRequest
    401 Unauthorized ProblemDetails

    Update the amount of a non validated transaction.

    HTTP Request

    POST /api/v1.0/transaction/amount

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

    Request Body application/json - UpdateTransactionRequestAmount

    Name Type Description
    TransactionRequestId string Transaction request id.
    NewAmount number New transaction amount.

    Responses

    Code Description Schema
    200
    400 The request is not valid. For example the transaction is validated, or the new amount is greater than the original amount. CustomBadRequest
    401 ProblemDetails

    Validate a transaction request

    HTTP Request

    POST /api/v1.0/transaction/validate

    Parameters

    Name Located in Description Required Type
    Idempotency-Key header Idempotency key

    Request Body application/json - ValidateTransactionRequest

    Name Type Description
    TransactionRequestId string The transaction request id.

    Responses

    Code Description Schema
    200
    400
    • INVALID_BUYER_PAYMENT_SESSION_STATUS : The payment session is not alive.
    • TRANSACTION_REQUEST_NOT_EXISTS : The transaction request does not exist.
    • TRANSACTION_REQUEST_IS_CANCELED : The transaction request is canceled.
    • TRANSACTION_REQUEST_IS_ALREADY_VALIDATED : The transaction request is already validated.
    • INVALID_TRANSACTION_REQUEST_STATUS : The transaction request should need the partner validation.
    CustomBadRequest
    401 ProblemDetails

    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
    CustomBadRequest
    401 ProblemDetails

    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.

    BuyerDetails

    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.
    Id string The buyer id.
    CompanyName string The company name.

    ValidationError

    Name Type Description
    PropertyName string
    ErrorMessage string
    AttemptedValue
    ErrorCode string

    CustomBadRequest

    Name Type Description
    ErrorCode string
    Errors array
    TraceId string

    ProblemDetails

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

    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.

    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.

    TransactionRequest

    Name Type Description
    MerchantId string The Merchant identifier
    MerchantTransactionNumber string The Merchant Transaction number
    Amount number The Transaction amount
    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.
    AdditionalData string Additional information sent by Merchant, optional
    Validated boolean Indicate whether the transaction should be immediately financed when the payment is accepted, or we should wait until the transaction request is validated to proceed to the transaction request financing.

    InitiatePaymentRequest

    Name Type Description
    TotalAmount number The payment total amount.
    SuccessCallbackUrl string The callback url to which the Buyer will be redirected if the Payment 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 Payment 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).
    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.
    AdditionalData string Additional information, optional
    TransactionRequests array Payment session transaction requests list.

    InitiateTransactionResponse

    Name Type Description
    RequestId string The transaction request identifier.
    MerchantId string The Merchant identifier
    MerchantTransactionNumber string The Merchant Transaction number
    AdditionalData string Additional information, optional

    InitiatePaymentResponse

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

    InitiateBuyerAutoAcceptedPaymentRequest

    Name Type Description
    TotalAmount number The payment total amount.
    BuyerId string The Buyer identifier.
    ProductId string The Product identifier.
    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.
    AdditionalData string Additional information, optional
    TransactionRequests array Payment session transaction requests list.

    InitiateBuyerAutoAcceptedPaymentResponse

    Name Type Description
    RequestId string The payment request identifier.
    InitiateTransactionsResponse array Created transactions.

    CancelPaymentRequest

    Name Type Description
    PaymentId string The payment session id.

    PayoutTransactionDetail

    Name Type Description
    Amount number The transaction amount.
    MerchantNumber string The transaction merchant number.
    Id string The transaction identifier.

    PayoutCreditNoteDetail

    Name Type Description
    Amount number The credit note amount.
    TreatedAmount number The amount of the credit note that was deducted from the total transactions amount.
    MerchantNumber string The credit note merchant number.
    OriginalTransactionId string The credit note related transaction identifier.

    PayoutDetail

    Name Type Description
    Id string The payout identifier.
    MerchantId string The merchant identifier.
    PaymentDate string The bank transfer date.
    Amount number The bank transfer amount.
    BankTransferLabel string The bank transfer label.
    Transactions array Transactions list concerned by the bank transfer.
    CreditNotes array Credit notes list concerned by the bank transfer.

    UpdatePartnerIbanRequest

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

    CancelTransactionRequest

    Name Type Description
    TransactionRequestId string The transaction request id.

    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

    UpdateTransactionRequestAmount

    Name Type Description
    TransactionRequestId string Transaction request id.
    NewAmount number New transaction amount.

    ValidateTransactionRequest

    Name Type Description
    TransactionRequestId string The transaction request id.

    TransactionRequestStatus

    Name
    Validated
    PendingPartnerValidation
    Canceled
    PartnerValidationExpired
    Financed

    TransactionDetail

    Name Type Description
    Id string Finexpay transaction id.
    PaymentSessionId string Finexpay payment session 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
       Validated
       PendingPartnerValidation
       Canceled
       PartnerValidationExpired
       Financed
    MerchantPaymentDate string Merchant payment date.
    ServerWebHookUrl string Server to server notification url.
    AdditionalData string Additional information sent by Merchant, optional