Skip to main content
USAePay is a US-based card payment gateway owned by NMI, providing secure payment processing solutions for merchants in the United States.

​
Setup

USAePay provides a self-service sign-up for a sandbox account. To sign up for an account, visit the sign-up page and create an account.

​
Credentials

Configure the following credentials in the Gr4vy dashboard, which are obtained from your USAePay administrator portal under Settings → API Keys:
  • API Key - Your USAePay API key for authentication
  • PIN - Your USAePay PIN for API access
  • Webhook Signature Key (optional) - Your webhook signature key for verifying webhook authenticity
USAePay API Key

​
Connector configuration

After setting up your USAePay connector in the dashboard, configure how transactions are routed to it. Choose one of the following options:
  • Using Flow - Configure USAePay as the target connector in Flow to automatically route card transactions to this connector
  • Using the API - Explicitly set the payment_service_id parameter to the USAePay connector ID when creating transactions. This overrides any Flow routing rules.
The connector ID can be found in the dashboard under Connections -> Configured connections.

​
Capabilities

​
Supported countries

​
Supported currencies

​
Limitations

  • Refunds before settlement - Captured transactions cannot be refunded until they are settled. Voiding a transaction before settlement is not currently supported.
This is a closed-loop connector. Some failover scenarios are limited. For details, see Open-loop versus closed-loop.

​
Integration

To accept card payments with USAePay, use one of Gr4vy’s client-side integration methods to securely collect card details. Due to PCI compliance requirements, card data should never be sent directly to your servers. You can integrate using:
  • Embed - A pre-built, customizable payment form that handles the complete payment flow
  • Secure Fields - Embed card input fields for building custom payment forms while maintaining PCI compliance
  • Mobile SDKs - Native SDKs for iOS, Android, React Native, and other platforms
These methods handle card data collection and tokenization. Once the card details are collected and tokenized, create a transaction through the Gr4vy API, which automatically routes the payment to your configured USAePay connection based on your Flow rules or explicit payment_service_id parameter.

​
Webhooks

Webhooks need to be configured in the USAePay administrator portal under Settings → Webhooks. Copy the webhook subscription URL from the Gr4vy dashboard and add it to the Hook URL field in the USAePay webhook configuration.
USAePay Webhook Configuration
If webhook signature verification is desired, enable this in the USAePay webhook configuration. Copy the Signature Key from the bottom of the webhook configuration window in USAePay’s administrator portal, and provide this value in the Webhook Signature Key field when configuring the connector credentials in the Gr4vy dashboard.

​
Idempotency

USAePay supports idempotent retries, but this must be configured in the USAePay administrator portal and is linked directly to the API key. By default, the Duplicate Transaction Handling field is set to None. There are 3 options to choose from, and only the Signature Key option is supported by Gr4vy. There is also a Time Limit field that allows you to set a limit for evaluating duplicate transactions.