EMI Partner API Integration Guide For AI agents: visit https://docs.payb.is/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI. Jump to Content Status page GuidesRecipesAPI ReferenceChangelog v4.1.12Status page Guides v4.1.12GuidesRecipesAPI ReferenceChangelog EMI Partner API Integration Guide About Paybis Welcome to Paybis Why Integrate with Usgetting started Integration Process Whitelabel SetupRamps Fiat-to-Crypto On Ramp Crypto-to-Fiat Off Ramp Capabilities and Coverage Supported Assets Supported Countries Payment Methods Payout Methods Ramps Integration Guides Choosing the Right Integration Path Platform Compatibility & Limitations Web: API-Based Integration Web: Standalone Integration Generating HMAC Signatures Web SDK Embedded Mode Standalone Integration Guide Custom Frontend Integration: Technical Requirements Internal Events Helpful Tips Mobile: iOS SDK Mobile: Android SDK Mobile: SDK Integration on Flutter Apps Ramp SDK for React Native Use cases Frictionless Off-Ramping for Wallets One-click checkout One-click login and checkout via Apple Pay Promo codes for buying/selling crypto Customizing User Journeys: Remove Any Friction Supply user email and wallet Single sign-on (SSO) Reusable KYC (Shared KYC) Set default payment method Control transaction fiat, crypto and amount Auth key login Set payment method for Google Pay, Apple Pay, and Credit CardsCorporate ramps Product Overview Integration Guide KYB Onboarding Guide Supported Assets Payment and Payout MethodsPaybis Send Product Overview Crypto Pay-outs Integration Guide Fiat Pay-outs Integration Guide Crypto Pay-ins Integration Guide Partner Portal Overview Send Crypto Payouts Send Fiat Payouts Transaction Overview Capabilities and Coverage Supported AssetsPartner portal Product Overview Left-side panel and Dashboard Profile SettingsHElp and support Partner support portalRAMP Integration for EMI EMI Partner API Integration Guide Powered by 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 Authorization 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: Authorization (string, required) - your API key. ParameterTypeDescriptionrequestIdstring (UUID)The unique identifier of the payment request that was generated when the widget session was created. Success response (HTTP 200) JSON { "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 Status codeDescription400 Bad RequestReturned if the requestId is malformed or if Paybis cannot locate the EMI payment. The response body contains a status field set to 400 along with a machine‑readable code and a human‑readable message. (The upstream 404 Not Found error from the internal service is translated into a 400 to avoid leaking implementation details.)401 UnauthorizedMissing or invalid API key.403 ForbiddenThe API key is valid but the partner account is disabled or lacks access to EMI functionality.422 Unprocessable EntityReturned if the requestId does not conform to the UUID format. Send EMI payment status webhook HTTP method: POST Endpoint: /v2/webhook/emi Headers: Authorization (string, required) - your API key. X‑Request‑Signature (string, required) - Base64‑encoded RSA signature of the raw request body Request body JSON { "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 Status codeDescription400 Bad RequestThe payload is missing required fields or contains invalid data (for example, unsupported status values or mismatched amounts/currencies). The response body returns the error code and message for debugging.401 UnauthorizedThe API key is missing or invalid.403 ForbiddenSignature verification failed or the partner account is disabled.409 ConflictA webhook for this payment was already received; duplicate notifications are ignored.422 Unprocessable EntityValidation errors such as invalid UUID formats. Field notes FieldRequiredAllowed values / formatRules & validations (short)ExamplestatusYescompleted \failedcompleted = funds irrevocably settled in EMI account; failed = cancelled/reversed/not processedcompletedreasonConditionallyShort textRequired if status=failed; keep brief (e.g., “insufficient funds”)cancelled by userpartnerPaymentIdYesString (unique per payment)Your payment ID; stored by Paybis for reconciliationpay_789012partnerUserIdYesStringMust equal the partnerUserId from initial request; reject if mismatchuser_345678bankRequisitesYesObject: bankName, bankAddress, accountHolderName, iban, swiftEcho exactly what was used; must match GET /v2/request/{requestId}/payment-details/emi; mismatch ⇒ “corrupted”, manual review{…iban: "DE89…", swift: "EXAMPLEBANK"} 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. Updated about 1 month ago Partner support portal Did this page help you? Yes No Copy Page Prerequisites Introduction Overview of the Flow Authentication API key Request signature Payment Flow Details Retrieve EMI payment details Send EMI payment status webhook Field notes Best practices