Developer Documentation

Payment APIs Documentation

The FinvyPay Payment API provides a unified interface for processing payments across multiple payment methods, including card payments, alternative payment methods (APM), crypto payments, and payment links.

Secure & Compliant

Bank-level encryption and enterprise-grade infrastructure to protect your transactions.

Fast Processing

Real-time transaction processing with optimized infrastructure for fast responses.

Global Support

Multi-currency support and international payment methods for global reach.

API Key Authentication

Secure API key-based authentication for all payment endpoints.

API Categories

Card Payments

Process credit and debit card payments with server-to-server or hosted payment pages.

APM Payments

Accept alternative payment methods like PayPal, Apple Pay, and Google Pay.

Refunds

Process full or partial refunds for successful transactions.

Payment Links

Create shareable payment links for customers to complete payments.

Crypto Payments

Accept cryptocurrency payments, create crypto payment links, and process crypto exchanges.

Status

Check the status of a payment or transaction by FinvyPay transaction ID.

Base URL & Environments

All API requests should be made to the following base URL:

Base URL

bash

https://api.finvypay.com

The difference between production and sandbox environments is in the API path:

Production

bash

https://api.finvypay.com/api/v1/production/...

Sandbox (Testing)

bash

https://api.finvypay.com/api/v1/sandbox/...

Note

Use the sandbox environment for testing and development. All sandbox transactions are simulated and do not process real payments.

Authentication

All payment API endpoints require authentication using an API key. Include your API key in the Authorization header:

Authorization Header

bash

Authorization: Bearer your_api_key_or_sandbox_api_key

Important

Keep your API keys secure. Never expose them in client-side code or commit them to version control. Use environment variables or secure key management systems.

You can obtain your API keys from your merchant dashboard after completing the onboarding process.

API Versioning

The Payment API uses versioning in the URL path. The current version is v1.

bash

/api/v1/production/card
/api/v1/sandbox/card

Note

When we release breaking changes, we will increment the version number. We will provide migration guides and maintain backward compatibility for a reasonable period.

Request & Response Format

Aspect	Details
`Content-Type`	All requests must include the `application/json` header.
Request Body	Request bodies should be JSON-encoded objects.
Response Format	All responses are JSON objects. Successful card payment responses return a `200 OK` status code with `success`, `status`, and a `data` object.

Success Response Example

json

{
  "success": true,
  "status": "SUCCESS",
  "data": {
    "amount": 100,
    "currency": "USD",
    "order_id": "ORD-12345",
    "txn_id": "FP260231SJWKL80027",
    "firstName": "John",
    "lastName": "Doe",
    "address": "12, Hill",
    "city": "Nevada",
    "state": "Nevada",
    "country": "US",
    "email": "john@example.com",
    "webhookUrl": "https://your-domain.com/webhook"
  }
}

For 3D Secure flows, the response includes status: "REDIRECT" and an is3DS URL to redirect the customer for authentication.

3DS Redirect Response Example

json

{
  "success": true,
  "status": "REDIRECT",
  "data": {
    "amount": 100,
    "currency": "USD",
    "order_id": "ORD-12345",
    "txn_id": "FP260231SJWKL80027",
    "firstName": "John",
    "lastName": "Doe",
    "address": "12, Hill",
    "city": "Nevada",
    "state": "Nevada",
    "country": "US",
    "email": "john@example.com",
    "webhookUrl": "https://your-domain.com/webhook"
  },
  "is3DS": "https://api.finvypay.com/payment/sandbox/card?transactionId=FP260231SJWKL80027"
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

200 OKRequest succeeded

400 Bad RequestInvalid request parameters

401 UnauthorizedInvalid or missing API key

403 ForbiddenAPI key lacks required permissions

404 Not FoundResource not found

429 Too Many RequestsRate limit exceeded

500 Server ErrorServer error

Error Response Format

json

{
  "success": false,
  "status": "FAILED",
  "error": {
    "code": "INVALID_CARD",
    "message": "The card number is invalid"
  }
}

Rate Limits

To ensure fair usage and system stability, API requests are rate-limited:

Standard Tier100 requests per minute per API key

Premium Tier500 requests per minute per API key

Enterprise TierCustom rate limits based on agreement

Rate limit information is included in response headers:

bash

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Important

If you exceed the rate limit, you will receive a 429 Too Many Requests response. Wait until the reset time before making additional requests.

Idempotency

For payment endpoints, you can include an idempotencyKey in the request header to ensure that duplicate requests are not processed multiple times:

Idempotency Header

bash

Idempotency-Key: unique-key-per-request

If you make the same request (with the same idempotency key) multiple times, only the first request will be processed. Subsequent requests will return the same response as the first request.

Note

Idempotency keys should be unique per transaction. Use a UUID or a unique identifier from your system.

Webhooks

Webhooks allow you to receive real-time notifications about transaction status changes. Configure your webhook URL when creating a payment, and we will send POST requests to your endpoint when events occur.

SUCCESSTransaction successfully processed

FAILEDTransaction failed

BLOCKEDTransaction blocked due to security/compliance

Webhook requests include a signature header for verification:

bash

fs-webhook-hash: HMAC-SHA256 signature

Important

Always verify webhook signatures to ensure requests are from FinvyPay. The signature is generated using HMAC-SHA256 with your secret key. See the Webhook guide for details.

Payment Statuses

Transactions can have the following statuses:

SUCCESSPayment has been successfully processed

FAILEDPayment failed due to an error or insufficient funds

PENDINGPayment is pending and awaiting further action

INITPayment process has been initialized but not yet completed

REDIRECTUser has been redirected to a third-party page for payment completion

BLOCKEDPayment blocked due to security or compliance reasons

ABANDONEDPayment process was started but not completed by the user

Quick Start

Ready to get started? Here's a quick example of processing a card payment:

Example: Process Card Payment

bash

curl -X POST https://api.finvypay.com/api/v1/sandbox/card \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key_or_sandbox_api_key" \
  -d '{
    "orderId": "ORD-12345",
    "amount": 100,
    "currency": "USD",
    "cardNumber": "4111111111111111",
    "cardExpiryMonth": 12,
    "cardExpiryYear": 2025,
    "cvv": "123",
    "cardholderName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "address": "12, Hill",
    "city": "Nevada",
    "state": "Nevada",
    "country": "US",
    "zip": "12345",
    "ipaddress": "185.23.44.91",
    "webhookUrl": "https://your-domain.com/webhook",
    "returnUrl": "https://your-domain.com/payment/callback"
  }'

NextCard Payments