This guide provides a detailed overview of constructing and completing payment transactions on the Payments API. For more information on how RUN orchestrates payments, read on at the Run Developer Overview.
The Payments API leverages refresh tokens as defined by OAuth 2.0.
Due to the one-to-many architecture of the Payments API, the required fields outlined in this document uses a conservative approach so that with a single integration you can leverage as many of our supported gateways as possible. Your business requirements may lend itself to wanting to collect more data during a transaction (e.g. larger ticket amounts) or less data during a transaction (e.g. smaller ticket amounts and/or higher volumes of transactions). Discuss your business use case with your Integration Delivery lead, and we will advise on how best to construct your API calls for your business use case.
<aside> 💡 If you need access to Run Merchant or are having trouble generating your Payments API credentials, please reach out to your Integration Delivery lead.
</aside>
<aside> ⏳ In the UAT environment, the bearer token is set to expire after one month. In Production, this expiration is set to expire after one hour.
</aside>
Collect customer information using the Runner.js service for payment account information collection and tokenization and additional fields for any supplemental customer information to be sent with the transaction call.
Create API calls to the Reporting API using your access token. For all endpoints in this guide, you may target a specific attribute or multiple attributes using the URL.
Examples
URL: [<https://apps.runpayments.io/ords/sprint/api/3p/v1/transactions?q={"funding_master_id":"F1645093"}>](<https://apps.runpayments.io/ords/sprint/api/3p/v1/transactions?q=%7B%22funding_master_id%22:%22F1645093%22%7D>)
Data returned: All transactions with a Funding ID of “F1645093”.
URL: [<https://apps.runpayments.io/ords/sprint/api/3p/v1/transactions?q=>](<https://apps.runpayments.io/ords/sprint/api/3p/v1/transactions?q=>){"mid":"lsn4mdj1416v350j0001", "amount":100}
Data returned: All transactions for MID “lsn4mdj1416v350j0001” with an amount of $1.00.
The funding emulator runs daily with a batch out time of 9pm EST.
Charge is the initial step in accepting payments from a cardholder. This action requests permission from the bank to transfer money from cardholder to the merchant by authorizing the account and can also capture the funds in the same request if specified.
The Charge service supports a POST request that includes a JSON encoded list of fields defined for the service. The service responds with either an HTTP Exception, if there are errors, or a JSON-encoded response, if the request was successful. Within the response, the status of the transaction is described in the result value:
A capture can take place during the authorization (see ”capture” field in the request) or after the initial authorization is submitted via Capture endpoint.
<aside> ⚠️ If the capture request is delayed, please be aware that authorizations typically expire after seven days. Pending authorizations display as holds or pending transactions on a cardholder’s account until they expire or are captured.
</aside>
The Capture service queues the transaction amount for settlement. Capture can occur within the charge request or subsequently.
If the amount to be captured is greater than the authorized amount (tip adjustment), please ensure that the merchant is qualified to handle this capability. The service responds with either an HTTP Exception, if there are errors, or a JSON-encoded response, if the request was successful.
The Void or Refund service determines the necessary action to reverse a transaction. If a void is enacted, this will cancel a transaction that is either authorized or queued for capture. If a refund is enacted this will reverse a transaction that is in a settled status.
<aside> ⚠️ Partial refunds are supported if you specify the amount in the request. If the amount is omitted, the full amount will be refunded.
Please be aware that some banks impose maximum time limits (ex. 6 months) on performing a refund using a "trans_id”.
</aside>
© 2024 Run Payments LLC