Authorization, Captures, and Reversals

Authorization, Captures, and Reversals in Revolv3 API

Revolv3’s API allows merchants to authorize payments, capture funds, and reverse authorizations, providing a flexible and secure payment management system. This guide explains how to:

1. Authorize a payment (reserve funds without charging the customer immediately).

2. Capture a payment (finalize and charge a previously authorized payment).

3. Reverse an authorization (cancel a payment hold).

Each section includes API endpoints, request examples, and field explanations.

1. Payment Authorization

A payment authorization checks if sufficient funds are available on the customer’s card and places a hold on the amount. The funds are not charged until they are captured.

API Endpoint for Payment Authorization

{Api Root}/api/Payments/authorization

Sample API Request (Authorizing a Payment)

{
  "PaymentMethod": {
    "BillingAddress": {
      "AddressLine1": "100 Main",
      "AddressLine2": null,
      "City": "Santa Ana",
      "State": "CA",
      "PostalCode": "91111",
      "Country": "US"
    },
	  "BillingFullName": "John Doe",
    "CreditCard": {
      "PaymentAccountNumber": "4111111111111111",
      "ExpirationDate": "1025"
    }
  },
  "NetworkProcessing": {
    "ProcessingType": "initialInstallment",
    "OriginalNetworkTransactionId": null
  },
  "Amount": {
    "Value": 30.99
  }
}

Explanation of API Request Fields

Alternative Authorization Using a Stored Payment Method

Instead of passing full payment details, merchants can authorize a payment using an existing PaymentMethodId.

API Endpoint

{Api Root}/api/Payments/authorization/{paymentMethodId}

Request Payload Example

{
  "NetworkProcessing": {
    "processingType": "initialInstallment",
    "originalNetworkTransactionId": null
  },
  "Amount": {
    "value": 1.03
  }
}

1. Authorization Response

When an authorization is successful, the API returns a PaymentMethodAuthorizationId, which is required for capturing or reversing the payment.

Sample API Response

{
  "networkTransactionId": "431241081661798",
  "paymentMethodAuthorizationId": 2055,
  "paymentMethod": {
    "paymentMethodId": 6061,
    "billingAddressId": 7056,
    "billingAddress": {
      "addressId": 7056,
      "addressLine1": "381 Forest Ave. Suite C",
      "addressLine2": null,
      "city": "Laguna Beach",
      "state": "CA",
      "postalCode": "92651",
      "phoneNumber": null,
      "email": null,
      "country": "US"
    },
    "billingFirstName": "Joe",
    "billingLastName": "Smith",
    "merchantPaymentMethodRefId": null,
    "paymentMethodCreditCardDetails": {
      "paymentLast4Digit": "1111",
      "paymentExpirationDate": "0330"
    }
  }
}

Explanation of API Response Fields

1. Capturing an Authorized Payment

A capture request charges the customer’s account for a previously authorized amount.

API Endpoint for Capturing Funds

{Api Root}/api/Payments/capture/{paymentMethodAuthorizationId}

Sample Capture Request

{
  "CustomerId": null,
  "Invoice": {
    "MerchantInvoiceRefId": "ABC309500654810",
    "Amount": {
      "value": 1.03
    }
  }
}

Explanation of API Request Fields

Key Notes:

✔ The PaymentMethodAuthorizationId must be provided to capture the funds.

✔ A capture request must be made before the authorization expires (typically within 7 days).

1. Reversing an Authorization

If an authorized payment is no longer needed, it can be reversed to release the hold on funds.

API Endpoint for Authorization Reversal

{Api Root}/api/PaymentMethod/reverse-auth

Sample Reversal Request

{
  "PaymentMethodAuthorizationId": 1234
}

Explanation of API Request Fields

Key Notes:

✔ A reversal cancels the authorization, ensuring that the funds are no longer held.

✔ Once reversed, the authorization cannot be captured, and a new authorization is required to reattempt the payment.