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.

  runner.tokenize((res) => {
    
    // Collect transaction parameters from your payment form
    var extraDetails = {
      mid: 1234567890, // Your Sandbox MID
      amount: 10000,
      name: 'John Doe',
      email: 'noreply@runpayments.io',
      phone: '5555555555',
      address1: '101 Independence Mall W',
      address2: '',
      city: 'Philadelphia',
      region: 'PA',
      country: 'US',
      account_zip: '19106',
      address_country: 'USA',
      capture: 'Y', // Y - auth and charge ‘N’ - just auth
      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
      com_ind: 'E',
      cvn: 000,
      currency: 'USD'
    }
    // Convert payment object params to JSON object
    var params = JSON.stringify({
      ...extraDetails,
      account_token: res.account_token, // card number tokenized
      expiration: res.expiry,           // expiration
    });
  }

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.

  runner.tokenize((res) => {
    // Construct the call to your backend with Payments API data.
    var xhr = new XMLHttpRequest();
    xhr.open(”POST”, “https://example.com/charge”, true); // Your backend endpoint
    xhr.setRequestHeader('Content-Type', 'application/json');
    xhr.onerror = function (err) {
      // Error handling for Payments API call
      errorElement.textContent = typeof err === 'object' ? (err && err.error) || Object.keys(err).map((k) => err[k].join(' ')).join(' ') : JSON.stringify(err);
      errorElement.classList.add('visible');
      loaderElement.classList.remove('visible');
    };
    // Collect transaction parameters from your payment form
    var extraDetails = {
      mid: 1234567890, // Your Sandbox MID
      amount: 10000,
      name: 'John Doe',
      email: 'noreply@runpayments.io',
      phone: '5555555555',
      address1: '101 Independence Mall W',
      address2: '',
      city: 'Philadelphia',
      region: 'PA',
      country: 'US',
      account_zip: '19106',
      address_country: 'USA',
      capture: 'Y', // Y - auth and charge ‘N’ - just auth
      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
      com_ind: 'E',
      cvn: 000,
      currency: 'USD'
    }
    // Convert all payment object params to JSON object
    var params = JSON.stringify({
      ...extraDetails,
      account_token: res.account_token, // card number tokenized
      expiration: res.expiry,           // expiration
    });
    // Parse the transaction response details
    xhr.onreadystatechange = function() {
      if (xhr.readyState == XMLHttpRequest.DONE) {
        var resp = JSON.parse(xhr.responseText);
        if (resp['trans_id']) { // successful resp returns trans_id identifier
          successElement.querySelector('.token').textContent = resp['trans_id'];
        } else {
        // Failed transaction error-handling here...
        }
      }
    }
    // Send transaction to Payments API
    xhr.send(params);
  })};

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:

{
    "amount": "100.00",
    "resp_text": "Approval",
    "mid": "1234567890" // Your sandbox MID,
    "account_token": "9413367799381111" // Account token generated by Runner.js,
    "trans_id": "071968453245",
    "result": "A",
    "trans_date": "01/01/2025 18:00:00"
}

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