Skip to main content
A Payment Intent is Modem Pay’s way of capturing that a customer wants to pay a certain amount. You use it to kick off a payment and get a link your customer can use to pay securely.

​
The Payment Intent object

Here’s everything you can include when you create one:
  • amount: The total amount to be paid.
  • currency: The currency of the payment (optional).
  • payment_methods: A list of payment methods you’ll accept (optional), e.g. “card”, “bank”, “wallet”.
  • title: A title for the payment (optional).
  • description: A description of the payment (optional).
  • customer: The ID of the customer paying (optional).
  • customer_name: The customer’s name (optional).
  • customer_email: The customer’s email address (optional).
  • customer_phone: The customer’s phone number (optional).
  • metadata: Any extra information you want to attach to the payment (optional).
  • return_url: Where the customer is sent after they pay successfully (optional).
  • cancel_url: Where the customer is sent if they cancel (optional).
  • payment_method: A specific payment method to use (optional).
  • coupon: The ID of a coupon to apply (optional). If you include one, its discount is taken off the payment amount.
  • callback_url: The web address where Modem Pay sends you a notification once the payment has been handled.
  • skip_url_validation: Set this to true to skip Modem Pay’s usual checking of your cancel_url or return_url. You’ll mostly need this when those links are mobile app deeplinks, so customers land back inside your app.

​
What you get back

After you create a Payment Intent, here’s what comes back:
  • status: True or false — whether the Payment Intent was created successfully. true means it worked, false means it didn’t.
  • message: A short, readable note about how it went (e.g. “Payment intent created successfully. Please proceed to complete the payment.”).
  • data: An object holding the details of the Payment Intent. Inside it:
    • intent_secret: A secret key that protects the Payment Intent, needed to complete the payment.
    • payment_link: The link to the hosted payment page where your customer pays.
    • amount: The total amount to be paid, in the currency you set.
    • currency: The currency code (e.g. GMD for Gambian Dalasi) the payment is made in.
    • expires_at: A timestamp (ISO 8601 format) for when the Payment Intent expires. After this time, it’s no longer valid.
    • status: Where the Payment Intent currently stands. It can be one of:
      • requires_payment_method: A payment method is needed before going further.
      • processing: The payment is being handled right now.
      • successful: The payment went through.
      • failed: The payment didn’t go through.
      • cancelled: The payment was called off, either by the customer or the system.

​
In short

Payment Intents are how you start and keep track of a payment in Modem Pay. By keeping all the inputs and responses neatly organized, they let you control how and when payments happen while keeping things smooth for your customers.