Payments

APM Payments API

Create alternative payment method transactions in sandbox and production. Redirect customers to hosted checkout and receive status updates via webhooks.

Authentication

Base URL: https://api.finvypay.com

Request Headers

bash

Authorization: Bearer <secret_key>
Content-Type: application/json

API Keys

API	Key
Sandbox APM	`PA_TEST_...`
Production APM	`PA_LIVE_...`
Production APM status	`PA_LIVE_...`

REDIRECTCustomer must be redirected to complete payment

SUCCESSPayment completed successfully

FAILEDPayment failed or was declined

PENDINGPayment is still being processed

ABANDONEDCustomer abandoned the payment flow

BLOCKEDTransaction blocked by risk or compliance rules

Sandbox APM

POST

SandboxAPI Key

Creates a sandbox APM transaction and returns a frontend hosted page URL in is3DS.

Request Body

json

{
  "orderId": "ORD-12345",
  "amount": 20,
  "currency": "USD",
  "paymentMethod": "cash-app",
  "merchantProfileId": 1,
  "email": "buyer@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "phoneNumber": "+14155550100",
  "country": "US",
  "description": "Early access membership",
  "returnUrl": "https://your-domain.com/return",
  "webhookUrl": "https://your-domain.com/webhook"
}

Request Parameters

Parameter	Type	Description
`orderId`required	string	Unique per merchant
`amount`required	number	Payment amount (minimum 0.01)
`currency`required	string	Currency code (3 letters, e.g. USD)
`paymentMethod`required	string	APM identifier, e.g. cash-app, paypal
`merchantProfileId`optional	number	Merchant Profile ID. Defaults to PRIMARY profile if not provided
`email`required	string	Customer email address
`firstName`required	string	Customer first name
`lastName`required	string	Customer last name
`phoneNumber`required	string	Customer phone number. Use this field name, not phone
`country`required	string	Customer country (2-letter ISO code, e.g. US)
`description`required	string	Payment description
`returnUrl`required	string	Merchant page after payment complete
`webhookUrl`required	string	Webhook URL for SUCCESS/FAILED notifications

Response: Redirect

The response has status: "REDIRECT" and an is3DS field containing the hosted sandbox page URL. Send the user to this URL to complete the simulated payment.

Redirect to hosted sandbox page

200

json

{
  "success": true,
  "status": "REDIRECT",
  "message": "Redirect required",
  "is3DS": "https://app.finvypay.com/api/sandbox/apm?transactionId=FP26XXXXX00001",
  "data": {
    "amount": 20,
    "currency": "USD",
    "order_id": "ORD-12345",
    "txn_id": "FP26XXXXX00001",
    "firstName": "Jane",
    "lastName": "Doe",
    "country": "US",
    "email": "buyer@example.com",
    "webhookUrl": "https://your-domain.com/webhook"
  }
}

Production APM

POST

ProductionAPI Key

Creates a live APM payment. One redirect to the provider checkout URL (is3DS). After that, status comes from webhooks—no second backend redirect hop.

Same request body and required fields as sandbox. Use a live key (PA_LIVE_...).

Request Body

json

{
  "orderId": "d994ffed-ed4f-4b1a-a11a-6b0c48a061e2",
  "amount": 100.50,
  "currency": "USD",
  "merchantProfileId": 1,
  "paymentMethod": "cash-app",
  "email": "buyer@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "phoneNumber": "+14155550100",
  "country": "US",
  "description": "APM production payment",
  "returnUrl": "https://your-domain.com/return",
  "webhookUrl": "https://your-domain.com/webhook"
}

Request Parameters

Parameter	Type	Description
`orderId`required	string	Unique per merchant
`amount`required	number	Payment amount (minimum 0.01)
`currency`required	string	Currency code (3 letters, e.g. USD)
`paymentMethod`required	string	APM identifier, e.g. cash-app, paypal
`merchantProfileId`optional	number	Merchant Profile ID. Defaults to PRIMARY profile if not provided
`email`required	string	Customer email address
`firstName`required	string	Customer first name
`lastName`required	string	Customer last name
`phoneNumber`required	string	Customer phone number. Use this field name, not phone
`country`required	string	Customer country (2-letter ISO code, e.g. US)
`description`required	string	Payment description
`returnUrl`required	string	Merchant page after payment complete
`webhookUrl`required	string	Webhook URL for SUCCESS/FAILED notifications

Response: Redirect

Send the user to is3DS (provider hosted checkout). Final status is delivered via webhook.

Redirect to provider checkout

200

json

{
  "success": true,
  "status": "REDIRECT",
  "message": "Redirect required",
  "is3DS": "https://pay.payductor.com/pay/xxxxxxxx",
  "data": {
    "amount": 100.5,
    "currency": "USD",
    "order_id": "d994ffed-ed4f-4b1a-a11a-6b0c48a061e2",
    "txn_id": "FP26XXXXX00001",
    "firstName": "Jane",
    "lastName": "Doe",
    "country": "US",
    "email": "buyer@example.com",
    "webhookUrl": "https://your-domain.com/webhook"
  }
}

Error Response

400

json

{
  "success": false,
  "message": "No acquirer account found please contact admin"
}

Important

If no APM acquirer is assigned or active, the request fails with a clear error message. Contact support to configure your acquirer account.

Production APM Status

GET

ProductionAPI Key

Polls the provider if still pending/redirect, updates our DB, and returns the same shape as create (no is3DS). Use data.txn_id from the create response as :transactionId.

Request

bash

GET /api/v1/production/apm/FP26XXXXX00001/status
Authorization: Bearer PA_LIVE_...

No request body.

Success Response

200

json

{
  "success": true,
  "status": "SUCCESS",
  "message": "Payment completed",
  "data": {
    "amount": 100.5,
    "currency": "USD",
    "order_id": "d994ffed-ed4f-4b1a-a11a-6b0c48a061e2",
    "txn_id": "FP26XXXXX00001",
    "firstName": "Jane",
    "lastName": "Doe",
    "country": "US",
    "email": "buyer@example.com",
    "webhookUrl": "https://your-domain.com/webhook"
  }
}

While the customer is still on checkout, status is typically REDIRECT or PENDING.

Error Response

404

json

{
  "success": false,
  "message": "APM transaction not found"
}

Note

Returned for wrong key, sandbox transaction, or card transaction.

Production Flow

Production APM payments follow this frontend flow:

1
Create production APM payment
Call Production APM and receive is3DS and data.txn_id
2
Redirect to provider checkout
Redirect the browser to the is3DS URL
3
Wait for webhook updates
Do not wait for a return to our API. Provider webhooks update the transaction
4
Optional status polling
Poll Production APM status with txn_id if needed
5
Receive merchant webhook
Merchant webhookUrl is POSTed on SUCCESS/FAILED

Webhook Payload

When payment completes or fails, a POST request is sent to your webhookUrl:

Webhook Body

json

{
  "success": true,
  "status": "SUCCESS",
  "data": {
    "amount": 100.5,
    "currency": "USD",
    "order_id": "d994ffed-ed4f-4b1a-a11a-6b0c48a061e2",
    "txn_id": "FP26XXXXX00001",
    "firstName": "Jane",
    "lastName": "Doe",
    "country": "US",
    "email": "buyer@example.com",
    "webhookUrl": "https://your-domain.com/webhook"
  }
}

Webhook Headers

Header	Value
fs-webhook-hash	Webhook signature hash
Content-Type	application/json
X-Webhook-Attempt	Retry attempt number
X-Transaction-Id	FinvyPay transaction ID

PreviousCard Payments NextPayment Links