Modem Pay CLI

The Modem Pay CLI is a tool designed to simplify integration testing by offering features like authentication, webhook management, and event simulation in a test environment.

Installation

Ensure that both Node.js and npm are installed on your machine.

Install the Modem Pay CLI globally:

npm install -g modem-pay-cli

Commands

1. Login

Authenticate with your Modem Pay account to access CLI features.

modempay login

You'll be prompted to enter your Modem Pay email and password. Upon successful authentication, your credentials will be saved for subsequent commands.

2. Listen

Create a secure public tunnel to forward webhooks to your local endpoint, facilitating testing during development.

modempay listen --forward-url=http://localhost:3000/webhook

Replace http://localhost:3000/webhook with your local endpoint. This command will provide a public URL that forwards incoming webhooks to your specified local endpoint.

Note: The CLI uses Localtunnel to generate the public URL. In some cases, a public URL might not be provisioned successfully due to network issues. This feature should only be used in test environments.

3. Trigger

Simulate events to test your webhook handling.

modempay trigger <event-type>

Supported event types include:

• Customer Events: customer.created, customer.updated, customer.deleted
• Payment Intent Events: payment_intent.created, payment_intent.cancelled
• Charge Events: charge.succeeded, charge.cancelled

For example, to simulate a successful charge:

modempay trigger charge.succeeded

This will send a charge.succeeded event payload to your configured webhook endpoint for testing.

Important: Always respond to webhook events with an HTTP 200 OK status to confirm receipt. This ensures Modem Pay recognizes that your server has successfully processed the event.

4. Transaction

You can use the transaction commands to create (initialize) and verify payments via the CLI.

Initialize a Payment

To start a new payment (payment intent), run:

modempay transaction init --amount=<number> [--email=<customer-email>]

• --amount: Amount to request (required; must be a positive number).
• --email: (Optional) Customer's email for associating the payment intent.

Example:

modempay transaction init --amount=120 [email protected]

On success, you'll see details like:

✅ Payment Intent Created Successfully!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Payment Details
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Amount:         GMD 120
  Status:         REQUIRES PAYMENT METHOD
  Expires:        6/10/2025, 9:18:45 PM
  Intent ID:      b84ac35d-7a65....
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 Payment Link:
  https://test.checkout.modempay.com/make-payment/b84ac35d-7a65....

💡 Tip: Copy the link above to complete the payment

The Payment Link is where your customer should be sent to pay.

Verify a Payment

To check the status of a payment intent, use:

modempay transaction verify --id=<payment_intent_id>

• --id: ID of the payment intent you wish to check.

Example:

modempay transaction verify --id=b84ac35d-7a65....

This returns output like:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Payment Details
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Amount:         GMD 120.50
  Status:         SUCCESSFUL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 Payment Link:
  https://test.checkout.modempay.com/make-payment/b84ac35d-7a65....

💡 Tip: Copy the link above to complete the payment

Note:

• After a successful payment, the status will update (e.g., to SUCCESSFUL).
• If you forget your payment intent ID, you can find it in the CLI output from init or your Modem Pay Dashboard.

Documentation

For detailed information on setting up and handling webhooks, please refer to the Modem Pay Webhooks Documentation.