EMI Partner API Integration Guide

ℹ️

With this solution, EMI providers embed Paybis widget directly into their own platform while retaining control of the funds movement. Your system initiates and manages the bank transfer from customers’ accounts, while the widget supplies the quote, request, and bank-details experience in a clean, compliant UI. After you confirm irrevocable settlement via the signed webhook, Paybis finalizes fulfillment (ecrypto release). The result is native, seamless user experience that stays inside your platform.

Prerequisites

Choose your integration path

• API-based integration (recommended for maximum control): Server-side creation of requests and direct calls to Paybis Partner API.
• Web SDK / embedded widget (fastest to launch): Front-end embed that emits internal events (emi-payment-created) your app listens to.

See the integration guide for available web options.

• Web: API-Based Integration
• Web: Javascript SDK
• Web: Embedded Mode

Widget supports multiple payment methods; for EMI use cases, we recommend the internal EMI method to deliver a seamless, near-instant user experience.

Introduction

ℹ️

This document provides instructions and API specifications examples for EMI partners to integrate with our platform. The integration allows your system to retrieve bank details necessary for processing payments and to notify our platform about the status of these transactions via webhooks.

GET /v2/request/{requestId}/payment‑details/emi - retrieve the bank account details needed to complete an EMI payment for a given request.

POST /v2/webhook/emi - send a webhook to Paybis confirming that an EMI payment has completed or failed.

Overview of the Flow

Payment initiation – front‑end embeds a Paybis widget. When the user selects the EMI payment option, the widget emits an orderId via an iframe event - emi-payment-created. Capture and persist this identifier; it links the EMI payment on your side to the corresponding transaction.

Retrieve bank details – once you have the orderId and the associated requestId, call GET /v2/request/{requestId}/payment‑details/emi with your API key. The response returns:

• Payment amount,
• Currency and
• Bank account details (bankRequisites) that the end user needs to transfer funds to.

Your system should use them internally to initiate the transfer.

Process the payment and notify Paybis – after the user’s transfer is processed in your EMI system, send a webhook to POST /v2/webhook/emi with the final status. Include the same orderId and requestId, the EMI payment identifier (partnerPaymentId), the user identifier on your side (partnerUserId) and the bank requisites used.

If the payment was successful, set status to completed; otherwise set status to failed and provide a human‑readable reason explaining the failure.

Authentication

API key

All requests must be authenticated using the API key issued during your onboarding. Include the key in the X‑API‑KEY HTTP header when calling Paybis endpoints. Keep your API key confidential and do not embed it in client‑side code or logs.

Request signature

Webhook notifications must be signed to protect against tampering. Use your private RSA key to compute a signature of the request body using the RSASSA‑PSS algorithm with SHA‑512. The resulting signature must be Base64‑encoded and sent in the X‑Request‑Signature header. Paybis will decode and verify the signature using the public key that you provided during onboarding. If signature verification fails, Paybis will return a 403 error. Never reuse a signature; a new signature should be generated whenever the request body changes.

ℹ️

Note

• Do not sign GET requests or any request with an empty body.
• The header name in Paybis documentation is X‑Request‑Signature; this replaces the placeholder X‑SIGNATURE used in earlier drafts.
• Use secure storage for your private key and rotate keys if you suspect compromise.

Payment Flow Details

Retrieve EMI payment details

HTTP method: GET

Endpoint: /v2/request/{requestId}/payment‑details/emi

Headers: X‑API‑KEY (string, required) - your API key.

Success response (HTTP 200)

{
  "amount": "123.45",
  "currency": "EUR",
  "orderId": "unique_order_identifier_string",
  "bankRequisites": {
    "bankName": "Example Bank",
    "bankAddress": "123 Bank Street, City, Country",
    "accountHolderName": "John Doe",
    "iban": "DE89370400440532013000",
    "swift": "EXAMPLEBANK"
  }
}

Error responses

Send EMI payment status webhook

HTTP method: POST

Endpoint: /v2/webhook/emi

Headers:

• X‑API‑KEY (string, required) - your API key.
• X‑Request‑Signature (string, required) - Base64‑encoded RSA signature of the raw request body

Request body

{
  "status": "completed",           // required, either "completed" or "failed"
  "reason": "string",              // optional, specify only if status is "failed"
  "amount": "123.45",              // required, the exact amount processed
  "currency": "EUR",               // required, ISO currency code
  "orderId": "unique_order_identifier_string",         // required, as received from the iframe event
  "partnerPaymentId": "string",    // required, your unique identifier for this payment
  "partnerUserId": "string",       // required, your user ID that matches the original request
  "requestId": "b7f323c7-...",     // required, the original request ID from Paybis
  "bankRequisites": {
    "bankName": "Example Bank",
    "bankAddress": "123 Bank Street, City, Country",
    "accountHolderName": "John Doe",
    "iban": "DE89370400440532013000",
    "swift": "EXAMPLEBANK"
  }
}

Success response (HTTP 204 No Content)

An empty response body indicates that Paybis successfully received and validated the webhook.

Error responses

Field notes

Best practices

• Store identifiers - Persist the orderId, requestId and partnerPaymentId so you can correlate your internal payments with the Paybis transaction. Do not rely on time stamps or amounts alone for reconciliation.
• Validate amounts and currencies - before sending the webhook, verify that the amount and currency reflect the actual settlement in your EMI system. Mismatched values will lead to payment rejection or manual investigation.
• Handle error responses gracefully - treat any non‑204 response from the webhook endpoint as a failure and log the response body. Retry sending the webhook only after resolving the underlying issue (e.g., fixing the payload or obtaining a new API key). Do not blindly retry on 400‑class errors.
• Protect credentials - safeguard both your API key and private RSA key. Rotate them periodically and immediately if you suspect compromise. Never expose them in client‑side code or unencrypted logs.
• Test in sandbox - use the sandbox environment (https://widget-api.sandbox.paybis.com) to test your integration end‑to‑end before going live. The sandbox accepts the same API calls and headers but does not move real funds.

By following this guide and adhering to the security recommendations for signing requests, you can integrate Paybis’ EMI payment option into your platform with confidence.