Accounts

The accounts resource in the OpenTrnasact API is an important feature for managing payment transactions. This resource allows for the creation and management of different account types, which can include payment account identifiers and credentials. The OpenTransact API securely stores sensitive information associated with these accounts, ensuring that transactions can be processed in a safe and secure manner. This resource allows for flexibility in managing different types of payment accounts, making it easier for applications to process transactions and manage financial information.

Data Types

AccountResponse

Key	Value
type	accounts
id	UUID
Attributes
nickname	String
status	new, active, or invalid
details	BankAccount, CreditCard, VaultedAccount, or ChinaBankAccount
metadata	Metadata
created-at	Timestamp
updated-at	Timestamp
Relationships
owner	OwnerRelationship

Example

{
  "data": {
    "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0",
    "type": "accounts",
    "attributes": {
      "nickname": "Chase Account",
      "status": "active",
      "details": {
        "type": "bank-accounts",
        "routing-number": "021000021",
        "account-holder-type": "business",
        "account-category": "checking"
      },
      "metadata": {},
      "created-at": "2022-06-21T23:34:04Z",
      "updated-at": "2022-06-21T23:34:04Z"
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "profiles",
          "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
        }
      }
    }
  }

CreateAccountRequest

Key	Value
type	accounts	Required
Attributes
nickname	String	Required
details	BankAccountParams, CreditCardParams, VaultedAccountParams, or ChinaBankAccountParams	Required
Relationships
owner	OwnerRelationship	Required

Example

{ 
  "data": {
    "type": "accounts",
    "attributes": {
      "nickname": "Chase Account",
      "details": {
        "type": "bank-accounts",
        "account-number": "4111111111111111",
        "routing-number": "021000021",
        "account-holder-type": "business",
        "account-category": "checking"
      }
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "profiles",
          "id": "$PROFILE_ID" 
        }
      }
    }
  }
}

UpdateAccountRequest

Key	Value	Required
type	accounts	Required
id	UUID	Required
Attributes
nickname	String
details	UpdateCreditCardParams
metadata	Metadata

If you do not provide any updatd attributes, only the updated-at timestamp will be updated.

Example

{
  "data": {
    "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0",
    "type": "accounts",
    "attributes": {
      "nickname": "Chase Account",
      "details": {
        "type": "bank-accounts",
        "account-number": "4111111111111111",
        "routing-number": "021000021",
        "account-holder-type": "business",
        "account-category": "checking"
      }
    }
  }
}

BankAccountParams

Key	Value
type	bank-accounts	Required
routing-number	String	Required
account-number	String	Required
account-holder-type	personal or business	Required
account-category	checking or savings	Required

BankAccountParams Example

{
  "type": "bank-accounts",
  "routing-number": "021000021",
  "account-number": "4111111111111111",
  "account-holder-type": "business",
  "account-category": "checking"
}

BankAccount

Key	Value
type	bank-accounts
routing-number	String
account-holder-type	personal or business
account-category	checking or savings

BankAccount Example

{
  "type": "bank-accounts",
  "routing-number": "021000021",
  "account-holder-type": "business",
  "account-category": "checking"
}

ChinaBankAccountParams

Key	Value
type	china-bank-accounts	Required
account	String	Required
bank	String
bank-branch	String

Either bank or bank-branch must be provided.

ChinaBankAccountParams Example

{
  "type": "china-bank-accounts",
  "account": "6227000048088888",
  "bank-branch": "123456"
}

ChinaBankAccount

Key	Value
type	china-bank-accounts
description	String
bank	String
bank-branch	String

ChinaBankAccount Example

{
  "type": "china-bank-accounts",
  "description": "My China Bank Account",
  "bank": "Bank of China",
  "bank-branch": "123456"
}

CreditCardParams

Key	Value	Required	Notes
type	credit-cards	Required
card-number	String	Required
cardholder-name	String	Required
billing-address-id	UUID	Required
expiration-date	String	Required	MMYY format
cvv	String

CreditCardParams Example

{
  "type": "credit-cards",
  "card-number": "4111111111111111",
  "cardholder-name": "John Smith",
  "billing-address-id": "e7765383-cb90-4494-8ea0-79564b1b857a",
  "expiration-date": "0126",
  "cvv": "997"
}

UpdateCreditCardParams

Key	Value
type	credit-cards	Required
cardholder-name	String
billing-address-id	UUID
cvv	String

UpdateCreditCardParams Example

{
  "type": "credit-cards",
  "cardholder-name": "John Wayne",
  "cvv": "997"
}

CreditCard

Key	Value	Notes
type	credit-cards
bin	String	First 8 digits of Card Number used to identify the Bank/Issuer
bin-details	BinDetails	Additional details about the BIN (requires subscription)
billing-address	BillingAddress
brand	CardBrand	Card Brand Identifier
card-holder-name	String
expiration-date	String
last-four	String	Last 4 digits of the card number

CreditCard Example

{
  "type": "credit-cards",
  "bin": "55555555",
  "bin-details": {},
  "billing-address": {
    "id": "e7765383-cb90-4494-8ea0-79564b1b857a",
    "street1": "111 PEACHTREE PLACE",
    "street2": null,
    "zipcode": "30345",
    "locality": "Atlanta",
    "sub-locality": null,
    "region": "GA",
    "country": "US",
  },
  "brand": "master",
  "card-holder-name": "John Smith",
  "expiration-date": "0126",
  "last-four": "4444"
}

BinDetails

Value
TBD

CardBrand

Value
visa
master
discover
american_express
diners_club
jcb
dankort
maestro
forbrugsforeningen
elo
alelo
cabal
naranja
union_pay
alia
olimpica
creditel

BillingAddress

Key	Value
id	UUID
street1	String
street2	String
zipcode	String
locality	String
sub-locality	String
region	String
country	String

BillingAddress Example

{
  "id": "e7765383-cb90-4494-8ea0-79564b1b857a",
  "street1": "111 PEACHTREE PLACE",
  "street2": null,
  "zipcode": "30345",
  "locality": "Atlanta",
  "sub-locality": null,
  "region": "GA",
  "country": "US"
}

VaultedAccountParams

Key	Value
type	vaulted-accounts	Required
vault-provider	String	Required
vault-identifier	String	Required
account-info	Object

VaultedAccountParams Example

{
  "type": "vaulted-accounts",
  "vault-provider": "stripe",
  "vault-identifier": "tok_1234567890"
}

VaultedAccount

Key	Value
type	vaulted-accounts
vault-provider	String
vault-identifier	String
account-info	Object

The account-info object is provider specific and is determined from data gathered from the external payment service.

VaultedAccount Example

{
  "type": "vaulted-accounts",
  "vault-provider": "stripe",
  "vault-identifier": "tok_1234567890",
  "account-info": {
    "stripe-customer-id": "cus_1234567890"
  }
}

GET/v1/accounts

List Accounts

This endpoint retreives a paginated list of Accounts. By default, a maximum of thirty Accounts are shown per page.

This endpoint returns an array of AccountResponse objects.

Filters

Name
owner_id
Type
string
Description
The ID of the Owner that owns the Account.
Name
owner_type
Type
string
Description
The type of the Owner that owns the Account.
Name
status
Type
string
Description
The status of the Account.
Name
created_between
Type
object
Description
See documentation for filtering by timestamps.
Name
updated_between
Type
object
Description
See documentation for filtering by timestamps.
Name
metadata
Type
object
Description
See documentation for filtering by metadata.
Name
page
Type
object
Description
See documentation for pagination.

Request

GET

/v1/accounts

curl -G https://api.opentransact.com/v1/accounts \
  -H "Authorization: Bearer {token}" \
  -H 'Content-Type: application/vnd.api+json'

Response

{
"data": [{
  "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
  "type": "accounts",
  "attributes": {
    "nickname": "Chase Account",
    "details": {
      "type": "bank-accounts",
      "routing-number": "021000021",
      "account-holder-type": "business",
      "account-category": "checking"
    },
    "status": "new",
    "metadata": {},
    "created-at": "2022-06-21T23:34:04Z",
    "updated-at": "2022-06-21T23:34:04Z"
  },
  "relationships": {
    "owner": {
      "data": {
        "type": "profiles",
        "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
      }
    }
  }
},
{
  id: ...,
},
"meta": {
  "count": 38,
  "page-count": 2,
  "current-page": 1
},
"links": {
  "self": "https://api.opentransact.com/v1/accounts?page%5Bnumber%5D=1&page%5Bsize%5D=30",
  "first": "https://api.opentransact.com/v1/accounts?page%5Bnumber%5D=1&page%5Bsize%5D=30",
  "last": "https://api.opentransact.com/v1/accounts?page%5Bnumber%5D=2&page%5Bsize%5D=30",
  "next": "https://api.opentransact.com/v1/accounts?page%5Bnumber%5D=2&page%5Bsize%5D=30"
}
}

POST/v1/accounts

Create an Account

This endpoint creates a new Account.

This endpoint accepts a CreateAccountRequest object and returns an AccountResponse object.

Request

POST

/v1/accounts

curl https://api.opentransact.com/v1/accounts \
  -H "Authorization: Bearer {token}" \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
        "data": {
          "type": "accounts",
          "attributes": {
            "nickname": "Chase Account",
            "details": {
              "type": "bank-accounts",
              "account-number": "4111111111111111",
              "routing-number": "021000021",
              "account-holder-type": "business",
              "account-category": "checking"
            }
          },
          "relationships": {
            "owner": {
              "data": {
                "type": "profiles",
                "id": "$PROFILE_ID"
              }
            }
          }
        }
      }'

Response

{
  "data": {
    "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
    "type": "accounts",
    "attributes": {
      "nickname": "Chase Account",
      "details": {
        "type": "bank-accounts",
        "routing-number": "021000021",
        "account-holder-type": "business",
        "account-category": "checking"
      },
      "status": "new",
      "metadata": {},
      "created-at": "2022-06-21T23:34:04Z",
      "updated-at": "2022-06-21T23:34:04Z"
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "profiles",
          "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
        }
      }
    }
  }
}

GET/v1/accounts/:id

Show an Account

This endpoint retrieves an Account by providing its ID.

This endpoint returns an AccountResponse object.

Request

GET

/v1/accounts/4c72784e-fb2a-4858-8067-95b6e36d54c0

curl https://api.opentransact.com/v1/accounts/4c72784e-fb2a-4858-8067-95b6e36d54c0 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
    "type": "accounts",
    "attributes": {
      "nickname": "Chase Account",
      "details": {
        "type": "bank-accounts",
        "routing-number": "021000021",
        "account-holder-type": "business",
        "account-category": "checking"
      }
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "profiles",
          "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
        }
      }
    }
  }
}

PUT/v1/accounts/:id

Update an Account

This endpoint performs an update on an Account.

This endpoint accepts an UpdateAccountRequest object and returns an AccountResponse object.

Request

PUT

/v1/accounts/4c72784e-fb2a-4858-8067-95b6e36d54c0

curl -X PUT https://api.opentransact.com/v1/accounts/4c72784e-fb2a-4858-8067-95b6e36d54c0 \
  -H "Authorization: Bearer {token}" \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
        "data": {
          "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
          "type": "accounts",
          "nickname": "VISA Card Updated",
          "details": {
            "type": "credit-cards",
            "cardholder-name": "John Wayne",
            "cvv": "997"
          }
        }
      }'

Response

{
  "data": {
    "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
    "type": "accounts",
    "attributes": {
      "nickname": "VISA Card",
      "details": {
        "bin": "55555555",
        "bin-details": {},
        "last-four": "4444",
        "brand": "master",
        "cardholder-name": "John Smith",
        "expiration-date": "0126",
        "billing-address": {
          "street1": "111 PEACHTREE PLACE",
          "street2": null,
          "zipcode": "30345",
          "locality": "Atlanta",
          "sub-locality": null,
          "region": "GA",
          "country": "US",
          "created-at": "2022-06-21T23:22:08Z",
          "updated-at": "2022-06-21T23:22:08Z",
          "id": "e7765383-cb90-4494-8ea0-79564b1b857a"
        },
        "type": "credit-cards"
      },
      "status": "new",
      "metadata": {},
      "created-at": "2022-06-21T23:34:04Z",
      "updated-at": "2022-06-21T23:34:04Z"
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "profiles",
          "id": "4c72784e-fb2a-4858-8067-95b6e36d54c0"
        }
      }
    }
  }
}