Payment Instruments API

Customers want to pay for their services using their preferred payment method. With the RevOps payment Instruments API, you have the flexibility to define credit card, ACH, or direct bank integrations using Plaid, on a per-customer basis. RevOps manages these Instruments and integrates with popular billing providers using industry-standard OAuth authentication flows.

Why manage Instruments with RevOps?

Your customer's payment preferences and billing details change over time: updated credit card details, migration to ACH for larger payments, technology upgrades to direct bank integrations. Having an automated way to update Instruments helps you respond quickly to your customer preferences.

Tokenization

In addition to the OAuth authentication, RevOps redacts sensitive PCI and PII data using tokenization. See Instrument model for which fields will be tokenized.

Note: The tokenization process may be different depending on the information being redacted.

Instruments Endpoints

Each endpoint assumes a default base url: https://vault.revops.io/v1/

Instruments List Resource

https://vault.revops.io/v1/accounts/:acct_id/instruments

Supported Methods:

  • GET - Retrieves a list of Instruments for an account
  • POST - Create a new Instrument for an account

URL Parameters

Name Description Required Schema
acct_id RevOps account identifier Yes string

API Key Accessibility

HTTP Method Public Key Secret Key
GET N/A
POST

CREATE INSTRUMENTS

POST /v1/accounts/:acct_id/instruments

Summary:

Creates a new Instrument for an account. Send as much information as possible for the payment method to improve validation and verification, and reduce fraud.

Description:

A new payment Instrument is created by sending a POST request to the resource URL /v1/accounts/:acct_id/instruments. The account must be a valid account and in good standing. Calls to blocked accounts will be rejected.

The primary required parameter method must be either credit-card or ach.

When method is credit-card, the following parameters are required:

  1. holder_name
  2. card_number
  3. card_expdate
  4. card_cvv
  5. postal_code

When method is ach, the following parameters are required:

  1. holder_name
  2. country
  3. currency
  4. account_number
  5. is_individual or is_business; At least one must be True

Additionally, for US based bank accounts, routing_number is required.

Any remaining fields are optional. If enough information is provided to verify the Instrument RevOps will automatically move the account to the active status.

If we are unable to automatically verify an ACH Instrument, then we will attempt a delayed-verification process that involves sending microdeposits to the customer's account. These deposits typically take 1-2 business days to appear and your customer will need to forward the values of the microdeposits back to your service. See Manual ACH Verification for a detailed example.

HTTP Response Codes

Code Description Schema
201 Created Instrument Instrument
400 Invalid request. API Error

Example

This example creates a credit card Instrument via the public key.

$> curl  https://vault.revops.io/v1/accounts/:acct_id/instruments \
        -X POST \
        -H 'Authorization: Bearer <public_key>' \
        -H 'Content-type: application/json' \
        -d '{"method": "credit-card", "card_expdate":{"month":"02","year":"2022"}, "holder_name":"First and Last Name","card_number":"4111111111111111","postal_code":"94109"}'

Here is the same example in python.

from uuid import uuid4
import urllib.request
import json

api_key = "pk_sandbox_<yourkey>" # or sk_sandbox_<yourkey>
api_url = "https://vault.revops.io/v1/accounts/:acct_id/instruments"

instrument = {
    'method': 'credit-card',
    'card_expdate': {
        'month':"02",
        'year':"2022"
    },
    'holder_name':"First and Last Name",
    'card_number':"4111111111111111",
    'postal_code':"94109",
    "is_primary": True
}

data = json.dumps(instrument).encode('utf8')

request = urllib.request.Request(
  api_url,
  method='POST',
  data=data,
  headers={
    'Content-type': 'application/json',
    'Authorization': "Bearer {}".format(api_key),
  },
)
try:
    with urllib.request.urlopen(request) as response:
        json_response = response.read().decode('utf-8')
        print(json.loads(json_response))
except urllib.error.HTTPError as httperror:
    print(httperror.read().decode('utf-8'))

GET INSTRUMENTS

GET /v1/accounts/:acct_id/instruments

Summary:

Returns a list of Instruments for the Account.

Example

$> curl  https://vault.revops.io/v1/accounts/:acct_id/instruments \
        -X GET \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json'

HTTP Response Codes

Code Description Schema
201 Instrument Instrument
400 Invalid request. API Error

Instrument Instance Resource

https://vault.revops.io/v1/accounts/:acct_id/instruments/:inst_id

Supported Methods:

  • GET - Retrieves an Instrument
  • POST - Updates existing Instrument
  • PUT - Creates and replaces the Instrument
  • DELETE - Detaches and/or deletes the Instrument
URL Parameters
Name Description Required Schema
acct_id RevOps Account identifier Yes string
inst_id Unique identifier for the Instrument generated by the API. Yes string

API Key Accessibility

HTTP Method Public Key Secret Key
GET N/A
POST N/A
PUT N/A
DELETE N/A

PUT INSTRUMENT

PUT /v1/accounts/:acct_id/instruments/:inst_id

Summary:

Creates and verifies an Instrument in RevOps. Including as much information as possible helps us validate the Instrument and reduce fraud.

Description:

A new Instrument is created by sending a PUT request to the resource URL. The current Instrument with the given id will be overridden.

HTTP Response Codes

Code Description Schema
201 Created Instrument Instrument
400 Invalid request. API Error

Example

$> curl  https://vault.revops.io/v1/accounts/:acct_id/instruments/:inst_id \
        -X PUT \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json' \
        -d '{"method": "credit-card", "card_expdate":{"month":"02","year":"2022"}, "holder_name":"First and Last Name","card_number":"4111111111111111","postal_code":"94109"}'
from uuid import uuid4
import urllib.request
import json

api_key = "sk_sandbox_<yourkey>"
api_url = "https://vault.revops.io/v1/accounts/:acct_id/instruments/:inst_id"

instrument = {
    'method': 'credit-card',
    'card_expdate': {
        'month':"02",
        'year':"2022"
    },
    'holder_name':"First and Last Name",
    'card_number':"4111111111111111",
    'postal_code':"94109",
    'is_primary': True
}

data = json.dumps(instrument).encode('utf8')

request = urllib.request.Request(
  api_url,
  method='PUT',
  data=data,
  headers={
    'Content-type': 'application/json',
    'Authorization': "Bearer {}".format(api_key),
  },
)
try:
    with urllib.request.urlopen(request) as response:
        json_response = response.read().decode('utf-8')
        print(json.loads(json_response))
except urllib.error.HTTPError as httperror:
    print(httperror.read().decode('utf-8'))

UPDATE INSTRUMENTS

POST /v1/accounts/:acct_id/instruments/:inst_id

Summary:

Updates an existing Instrument for an Account in RevOps.

Note: Best practice is to create a new Instrument rather than editing an existing Instrument because of the tokenization process.

Editable Credit Card Properties

Name Type Description
card_expdate CreditCardExpDate Credit card expiration date object.

Example

$> curl  https://vault.revops.io/v1/accounts/:acct_id/instruments/:inst_id \
        -X POST \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json' \
        -d '{"card_expdate": {"month": "03","year": "2022"}}'

Examples Response:

Note PCI and PII data is tokenized through the secure vault.

{
  "id": "inst_id",
  "uri": "/v1/accounts/:acct_id/instruments/:inst_id",
  "account_number": "",
  "bank_name": "",
  "card_cvv": "21312", // tokenized
  "card_expdate": {
    "month": "52b9f486-0158-4fdd-a365-19ccc05081d0", // tokenized
    "year": "4952" // tokenized
  },
  "card_number": "2454454410121111", // tokenized
  "card_token": "",
  "country": "US",
  "currency": "usd",
  "date_created": "2019-11-21T19:54:16.500173+00:00",
  "date_updated": "2019-11-21T19:54:16.500173+00:00",
  "holder_name": "tok_live_m9WDv2nG5tdHPo8PTH8SaQ", // tokenized
  "is_business": false,
  "is_individual": false,
  "last4": "",
  "method": "credit-card",
  "postal_code": "88302",
  "provider": "stripe",
  "provider_fingerprint": "fWKTP1Q3w3vPMP23",
  "provider_id": "pm_1FhLjHLPLN7dVpu1eXRWFjol",
  "provider_token": "",
  "routing_number": "",
  "status": "verified",
  "is_primary": false
}

Responses

Code Description Schema
200 Updated Instrument Instrument
400 Invalid request. API Error

DELETE

Summary:

The Instrument will be detached from the account to which it is attached. The Instrument may optionally be deleted from the account if the delete URL parameter is set to true. In either case, the Instrument will no longer be used for billing, and it will remain in the RevOps system with a status of deleted.

Description:

An Instrument can be detached and/or deleted by sending a DELETE request to the resource's URL.

URL Parameters
Name Description Required Schema
delete Whether to delete the payment method in addition to detaching it from the account. No boolean

Responses

Code Description
204 Successful operation. The server returns a 204 No Content status code if a deletion request is successful and no content is returned.
404 Account or Instrument record not found. The server returns a 404 Not Found status code if a deletion request fails due to the resource not existing.

Instruments Verification Resource

https://vault.revops.io/v1/accounts/:acct_id/instruments/:inst_id/verify

Supported Methods:

  • POST - Manually verify an ACH Instrument
URL Parameters
Name Description Required Schema
acct_id RevOps Account Identifier Yes string
inst_id Unique identifier for the Instrument generated by the API. Yes string

API Key Accessibility

Instrument verification methods are only accessible with secret key.

HTTP Method Public Key Secret Key
POST N/A

INSTRUMENT VERIFICATION

POST /v1/accounts/:acct_id/instruments/:inst_id/verify

Summary:

Verify microdeposit information for an unverified ACH Instrument. If the Instrument is already verified, the request will not be processed.

Description:

When we are unable to automatically verify an ACH Instrument, we will attempt a delayed-verification process that involves sending microdeposits to the customer's account. These deposits typically take 1-2 business days to appear. Your customer will need to forward the values of the microdeposits back to your service.

After you have collected the microdeposit amounts, use this endpoint to complete the ACH verification process. The request payload should adhere to InstrumentVerification.

See Manual ACH Verification for a detailed example.

HTTP Response Codes

Code Description Schema
200 Instrument verified N/A
400 Invalid request. API Error

Example

$> curl  https://vault.revops.io/v1/accounts/:acct_id/instruments/:inst_id/verify \
        -X POST \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json' \
        -d '{"method": "ach", "amounts": [32, 45]}'

Reveal Instrument Tokens Resource

https://vault.revops.io/v1/accounts/:acct_id/instruments/:inst_id/reveal

Supported Methods:

  • GET - Reveal Instrument Tokens
URL Parameters
Name Description Required Schema
acct_id RevOps Account Identifier Yes string
inst_id Unique identifier for the Instrument generated by the API. Yes string

API Key Accessibility

Instrument reveal methods are only accessible with secret key.

HTTP Method Public Key Secret Key
GET N/A

Models

Instrument

Instrument represents payment instrument information.

Name Type Description Tokenized
id string id is a globally unique identifier addressing the Instrument.
method string Payment method type. Possible values are credit-card or ach.
is_primary boolean Indicates whether the Instrument is the default method of payment.
country string Country that the payment Instrument has been issued in.
currency string Currency of the payment Instrument.
holder_name string If credit-card, the cardholder name associated with the credit card. If ach, the name of the bank account holder.
is_individual boolean True if the account holder is an individual.
is_business boolean True if the account holder is a business or corporation.
status string The status of the Instrument.
last4 string Last four digits of the Instrument. (May not always be present).
bank_name string Name of the bank.
account_number string Account number of the bank account.
routing_number string Routing number of the bank account.
card_number string Full credit card number.
card_expdate CreditCardExpDate Credit card expiration date object.
card_cvv string Card verification value.
postal_code string Postal code of the Instrument
provider string String identifier of the billing provider. Possible values: stripe
provider_fingerprint string Provider specific fingerprint of the Instrument.
provider_token string Provider specific token associated with the Instrument.
provider_id string External unique identifier of the Instrument in the provider's system
uri string RevOps assigned URI for accessing the Instrument record through a GET request.

Instrument Statuses

Name Description
error RevOps has detected an error with the Instrument. Typically indicates a failed charge
unverified The Instrument has been created but has not been verified with the billing provider.
verified The Instrument is valid and can be charged.
deleted This status indicated that the Instrument as been deprovisioned.

CreditCardExpDate

CreditCardExpDate represents credit card expiration date information

Name Type Description Required
month string Credit card expiration month Yes
year string Credit card expiration year Yes

InstrumentVerification

InstrumentVerification represents the information needed to verify an Instrument.

Name Type Description Required
method string Payment method type. Possible values are credit-card or ach Yes
amounts list List of ACH microdeposit amounts. Yes

API Error Response Format

The standard API response format is used to indicate when we were not able to process the request.

Name Type Description
code integer RevOps Error Code
type string RevOps Error Code
message string Human readable description of the error code