Finanpay

What is Finanpay?

Finanpay is an orchestrator of new digital purchase, payment, and financing services that help merchants sell more.

Concepts

Merchant Registration

Before a merchant can operate with Finanpay, a registration process must take place. This process involves submitting information and documentation related to the merchant. In summary, the main points are:

Companies:

• Owner's ID document (If it is an EU NIE, also request a passport)
• Bank ownership certificate
• Form 200 (if not available, request Form 390, and if 390 is not available, request the 303 forms for the current year's quarters)
• Tax ownership card (CIF)
• Declaration of beneficial ownership (portal document)
• ID document of individuals listed in point 5
• Extract from the Commercial Registry from Registradores de España with a valid date of less than 3 months
• Articles of incorporation (Only for Soyou)

Important: If one of the major owners (>25% of the company) is a company, all listed documents must be requested.

Self-employed:

• ID document (If it is an EU NIE, also request a passport)
• Tax ownership card (Form 036)
• Income tax return
• Bank ownership certificate

Technical Integration

The integration primarily involves a REST API call with a JSON message that will allow us to obtain a web address (URL) to present to the consumer’s browser.

This URL will lead the consumer to a page where they will see a summary of their purchase and a financing simulator.

Once the financing plan that best suits their needs is selected, the validation process begins. This validation process will include the following steps:

1. Request personal information
2. Capture card details to authenticate the cardholder and make the first installment payment
3. Notify the merchant so they can complete the order and fulfill it

Once the consumer is deemed eligible for the loan, a monthly recurring payment plan is automatically generated. The installment payment date will always be the same as the first payment date.

The following diagram illustrates the steps explained in this section:

Tips

It is important for the integrator to ensure that the cart does not change once the financing amount has been calculated.

The technical integration should be able to lock the cart so no user can add or remove items that modify the content and amount.

Failure to implement this correctly could add additional risk in the financing approval phase, potentially causing rejections and lowering the merchant’s conversion rate due to technical, not usability, issues.

Quick Start

The quick start for integration involves implementing the main API call that returns a web link directly to the installment simulation form and customer onboarding.

This link will have three possible terminations:

• Successful processing "success"
• Failed processing "failure"
• The user canceled the operation "cancel"

In the case of "success," the merchant must always make a confirmation call to finalize the financial operation and close the order in the merchant's sales system.

API integration details can be found at this link. Review the following sections:

• API Authentication
• API Requests
• API Responses

Step One: Generate Financing URL

POST /payment/api/v1/

The purpose of this step is to obtain a request_id that allows for operation confirmation. To obtain this value, the process must complete the merchant’s URL prepared to capture the OK status. In integration terms, this URL is called payload.redirect_after.success.

Example request for a 300€ operation:

Body
{
  "key": "key-value",
  "resource": "resource-value",
  "mode": "sha256",
  "nonce": "1234567890",
  "payload": {
    "amount": 30000,
    "currency": "EUR",
    "cart": {
      "items": [{
        "sku": "SKUVALUE1",
        "tax": "1",
        "name": "Item name 1",
        "quantity": "2",
        "amount": 70,
        "image": "https://url_to_optional_item_image/",
        "shipping": "2"
      },
      {
        "sku": "SKUVALUE2",
        "tax": "1",
        "name": "Item Name 2",
        "quantity": "2",
        "amount": 70,
        "image": "https://url_to_optional_item_image/",
        "shipping": "2"
       }
      ]
    },
    "redirect_after": {
      "cancel": "http://httpbin.org/get?status=cancel",
      "success": "http://httpbin.org/get?status=success",
      "failure": "http://httpbin.org/get?status=failure"
    }
  }
}

Parameter	Description
key	Merchant identifier.
mode	sha256 or sha512 based on the hmac signature algorithm used.
resource	Merchant configuration resource identifier.
nonce	Unique request identifier, helps control data duplication. Recommended to use unix timestamp with maximum precision.
payload	Object containing the specific parameters for each request.
payload.amount	Amount in integer format and cents in the chosen currency. If the currency is euro and we want to show 20.25€, we multiply by 100 to get 2025.
payload.currency	ISO 4217 currency acronym. Example: EUR for euro. More at https://en.wikipedia.org/wiki/ISO_4217.
payload.redirect_after	Object with parameters that control the final redirection to the merchant, allowing the merchant to know the operation status to proceed with order closure.
payload.redirect_after.success	The operation was successful, and payment confirmation can proceed. The URL for this parameter will have the request_id value appended in QueryString format. Example: redirect_after.success=http://httpbin.org/get?status=success final url=http://httpbin.org/get?status=success&request_id=abcdefgh1234
payload.redirect_after.failure	The operation encountered a processing error. The URL for this parameter will have the request_id value appended in QueryString format. Example: redirect_after.success=http://httpbin.org/get?status=failure final url=http://httpbin.org/get?status=failure&request_id=abcdefgh1234
payload.redirect_after.cancel	The user clicked cancel or went back in the form. The URL for this parameter will have the request_id value appended in QueryString format. Example: redirect_after.success=http://httpbin.org/get?status=cancel final url=http://httpbin.org/get?status=cancel&request_id=abcdefgh1234

Example response (truncated and simplified):

Body
{
    "type": "resource.status",
    "code": "0",
    "detail": "Successful payment request.",
    "payload": {
        "url": "https://sandbox.sipay.es/payment/api/v1/6242d085b19538c1ea4ccff1/fastpay",
        "finanpay": {
            "url": "http://localhost:8080/payment/api/v1/6242d085b19538c1ea4ccff1/finanpay",
            "supports_card_data": false,
            "supports_security_data": false,
            "supports_tokenization": false,
            "supports_refund": false,
            "supports_recurring": false,
            "available_card_capturers": [],
            "supports_direct_payment": true,
            "direct_url": "https://sandbox.sipay.es/payment/api/v1/6242d085b19538c1ea4ccff1/vivo/direct"
        }
    },
    "request_id": "6242d085b19538c1ea4ccff1",
    "uuid": "6242d085b19538c1ea4ccff1"
}

We should use the url field and send it to the browser so the consumer can start the financing process. The request_id value is important to store as it will allow for subsequent operations such as:

• Operation confirmation
• Operation inquiry

Step Two: Send Customer Information

In this section, you will find instructions on how to send customer data. If the minimum data is not provided, the financing payment method will not appear.

Step Three: Confirm Operation

POST /payment/api/v1/{request_id}

Once we have obtained the request_id value, we will program this API request to confirm the operation and the financing plan.

Secret: test-secret

Headers
Content-Signature: c5150a4dd8f82ef243e9d84b3f362bc90a9adb7bf1c1d7bec474a485e2124273

Body
{
  "key": "key-value",
  "resource": "resource-value",
  "mode": "sha256",
  "nonce": "1234567890",
  "payload": {}
}

Parameter	Description
key	Merchant identifier.
mode	sha256 or sha512 based on the hmac signature algorithm used.
resource	Merchant configuration resource identifier.
nonce	Unique request identifier, helps control data duplication. Recommended to use unix timestamp with maximum precision.
payload	Object with specific parameters for each request. In this case, it will be empty because this is a quick start example, and no further customization is needed.

Example response:

response

Body
{
    "type": "resource.status",
    "code": "0",
    "detail": "Operation confirmed successfully",
    "payload": {
        ...
    },
    "request_id": "6242d085b19538c1ea4ccff1",
    "uuid": "6242d085b19538c1ea4ccff1"
}

Code 0 indicates that the operation has been successfully completed.