Process a Payment | Run Developers

Payments API Overview

This guide provides a detailed overview of sending transactions to our Payments API. Depending on the nature of your business, you may want to collect more or less data about your customer during a transaction. Your Integration Delivery lead will advise on how best to construct your API calls based on your business use case.

Requirements:

Before we can complete a transaction using the Payments API, you must have:

Payment Token generated using Runner.js or the tokenization tool within Run Merchant.
Payment API Credentials including the access_token and refresh_token. These can be generated in Run Merchant or provided by your Integration Delivery Lead.

Usage

Use the api_key and refresh_token to request a fresh API key from /api_keys/refresh.

Every api_key has an expiration of 1 hour. Every refresh_token has an expiration of 30 days.

Collect data using Runner.js for payment account tokenization and additional customer information to be sent with the API call.

1   runner.tokenize((res) => {
2     
3     // Collect transaction parameters from your payment form
4     var extraDetails = {
5       mid: 1234567890, // Your Sandbox MID
6       amount: 10000,
7       name: 'John Doe',
8       email: 'noreply@runpayments.io',
9       phone: '5555555555',
10       address1: '101 Independence Mall W',
11       address2: '',
12       city: 'Philadelphia',
13       region: 'PA',
14       country: 'US',
15       account_zip: '19106',
16       address_country: 'USA',
17       capture: 'Y', // Y - auth and charge ‘N’ - just auth
18       vault: 'Y', // Y - return vault_id in successful response - stores customer and card info in a vault object; N - does not store card/customer data
19       com_ind: 'E',
20       cvn: 000,
21       currency: 'USD'
22     }
23 
24     // Convert payment object params to JSON object
25     var params = JSON.stringify({
26       ...extraDetails,
27       account_token: res.account_token, // card number tokenized
28       expiration: res.expiry,           // expiration
29     });
30   }
31

Construct and send your API call to the Payments API using your access_token in the header. For this example, we are calling the /charge endpoint.

1   runner.tokenize((res) => {
2     // Construct the call to your backend with Payments API data.
3     var xhr = new XMLHttpRequest();
4     xhr.open(”POST”, “https://example.com/charge”, true); // Your backend endpoint
5     xhr.setRequestHeader('Content-Type', 'application/json');
6 
7     xhr.onerror = function (err) {
8       // Error handling for Payments API call
9       errorElement.textContent = typeof err === 'object' ? (err && err.error) || Object.keys(err).map((k) => err[k].join(' ')).join(' ') : JSON.stringify(err);
10       errorElement.classList.add('visible');
11       loaderElement.classList.remove('visible');
12     };
13 
14     // Collect transaction parameters from your payment form
15     var extraDetails = {
16       mid: 1234567890, // Your Sandbox MID
17       amount: 10000,
18       name: 'John Doe',
19       email: 'noreply@runpayments.io',
20       phone: '5555555555',
21       address1: '101 Independence Mall W',
22       address2: '',
23       city: 'Philadelphia',
24       region: 'PA',
25       country: 'US',
26       account_zip: '19106',
27       address_country: 'USA',
28       capture: 'Y', // Y - auth and charge ‘N’ - just auth
29       vault: 'Y', // Y - return vault_id in successful response - stores customer and card info in a vault object; N - does not store card/customer data
30       com_ind: 'E',
31       cvn: 000,
32       currency: 'USD'
33     }
34 
35     // Convert all payment object params to JSON object
36     var params = JSON.stringify({
37       ...extraDetails,
38       account_token: res.account_token, // card number tokenized
39       expiration: res.expiry,           // expiration
40     });
41 
42     // Parse the transaction response details
43     xhr.onreadystatechange = function() {
44       if (xhr.readyState == XMLHttpRequest.DONE) {
45         var resp = JSON.parse(xhr.responseText);
46 
47         if (resp['trans_id']) { // successful resp returns trans_id identifier
48           successElement.querySelector('.token').textContent = resp['trans_id'];
49         } else {
50         // Failed transaction error-handling here...
51         }
52       }
53     }
54 
55     // Send transaction to Payments API
56     xhr.send(params);
57 
58   })};
59

Store relevant data from the response payload in your database for reporting within your application. The trans_id can be used to retrieve a transaction’s full detail from the Reporting API. Below is an abbreviated sample of key response data:

1 {
2     "amount": "100.00",
3     "resp_text": "Approval",
4     "mid": "1234567890" // Your sandbox MID,
5     "account_token": "9413367799381111" // Account token generated by Runner.js,
6     "trans_id": "071968453245",
7     "result": "A",
8     "trans_date": "01/01/2025 18:00:00"
9 }

For additional endpoints and examples, jump to the Payments API Reference.