> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modempay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Intents

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.