",
"status": "sent",
"type": "invoice_message"
}
```
--------------------------------
### Example Invoice Response JSON
Source: https://developers.8am.com/reference/api
This is an example of the JSON response structure when searching for invoices. It includes pagination details (page, page_size, total_entries) and a list of invoice objects. Each invoice object contains detailed information such as creation and modification timestamps, status, amounts, and associated contacts and line items.
```json
{
"page": 1,
"page_size": 20,
"total_entries": 200,
"results": [
{
"id": "i_iXGj6u1uCgonbGQUI3hmu",
"created": {
"user": "org_Y2eJHCXVqjMlXL9EfmBfc",
"timestamp": "2018-06-07T18:10:58.386Z",
"client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
"client_inet_address": "66.90.249.23",
"client_country_code": "US",
"client_location": "30.2414,-97.7687",
"caller_inet_address": "66.90.249.23",
"caller_country_code": "US",
"caller_location": "30.2414,-97.7687"
},
"modified": {
"user": "org_Y2eJHCXVqjMlXL9EfmBfc",
"timestamp": "2018-06-07T18:12:04.920Z",
"client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
"client_inet_address": "66.90.249.23",
"client_country_code": "US",
"client_location": "30.2414,-97.7687",
"caller_inet_address": "66.90.249.23",
"caller_country_code": "US",
"caller_location": "30.2414,-97.7687"
},
"status": "draft",
"invoice_number": "000024",
"invoice_date": "2018-06-06T00:00:00.000Z",
"total_amount": 10000,
"total_amount_due": 10000,
"amount_paid": 0,
"test_mode": false,
"currency": "USD",
"bank_account_id": "bank_eZX3KANx7JyXDCrMQkdLj",
"owner_id": "org_Y2eJHCXVqjMlXL9EfmBfc",
"contact_id": "p_tup7e7S0e7LIE55qvgXAR",
"contact": {
"id": "p_tup7e7S0e7LIE55qvgXAR",
"test_mode": false,
"owner_id": "org_Y2eJHCXVqjMlXL9EfmBfc",
"preferred_email": "eripley@example.com",
"first_name": "Ellen",
"last_name": "Ripley",
"name": "Ellen Ripley",
"type": "person",
"sort_name": "Ripley Ellen",
"display_name": "Ellen Ripley"
},
"invoice_payments": [],
"items": [
{
"id": "li_5cCL6ufx4KcjsM3CJYskH",
"description": "Consulting fee",
"rate_per_quantity": "10000",
"quantity": "1",
"rate_type": "units",
"total": 10000
}
],
"line_items": [
{
"id": "li_5cCL6ufx4KcjsM3CJYskH",
"description": "Consulting fee",
"rate_per_quantity": "10000",
"quantity": "1",
"rate_type": "units",
"total": 10000
}
],
"invoice_messages": [],
"attachments": [],
"type": "invoice"
},
.
.
.
{
"id": "i_uYUXQfch0FBT46oyDnLKB",
"created": {
"user": "org_Y2eJHCXVqjMlXL9EfmBfc",
"timestamp": "2018-06-07T18:24:57.172Z",
"client_id": "c2eef76c8abc09f3c0a5da91edc45a3e8cb7dbf2f18cb4cbb11cd32d72802910",
"client_inet_address": "66.90.249.23",
"client_country_code": "US",
```
--------------------------------
### Example API Response for Contact Update
Source: https://developers.8am.com/reference/api
This is an example JSON response received after a successful contact update operation. It includes details about the contact, such as name, owner information, addresses, and email addresses. The response also contains metadata about the creation and modification of the contact and its associated data.
```json
{
"id": "p_blM1oUmbCckoIdvoSstgS",
"created": {
"user": "admin@example.com",
"timestamp": "2022-01-19T18:17:20.305Z",
"client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
"client_inet_address": "97.65.251.242",
"client_country_code": "US",
"client_location": "30.2971,-97.7862",
"caller_inet_address": "97.65.251.242",
"caller_country_code": "US",
"caller_location": "30.2971,-97.7862"
},
"modified": {
"user": "admin@example.com",
"timestamp": "2022-01-19T18:36:20.876Z",
"client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
"client_inet_address": "97.65.251.242",
"client_country_code": "US",
"client_location": "30.2971,-97.7862",
"caller_inet_address": "97.65.251.242",
"caller_country_code": "US",
"caller_location": "30.2971,-97.7862"
},
"test_mode": true,
"name": "Clark Kent",
"sort_name": "Kent Clark",
"source_id": "partnername:1192022",
"preferred_email": "ckent@example.com",
"contact_code": "0031",
"owner_id": "org_ayVmT9zfkH46buQT4HtBK",
"owner": {
"id": "org_ayVmT9zfkH46buQT4HtBK",
"test_mode": false,
"owner_id": "org_a9p7cYn9MzBIL6egPb51O",
"preferred_email": "admin@example.com",
"name": "Example Company",
"sort_name": "Example Company",
"type": "organization",
"display_name": "Example Company"
},
"addresses": [
{
"id": "addr_qicRxmKYNEsDjLZEhlqE6",
"created": {
"user": "admin@example.com",
"timestamp": "2022-01-19T18:36:20.874Z",
"client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
"client_inet_address": "97.65.251.242",
"client_country_code": "US",
"client_location": "30.2971,-97.7862",
"caller_inet_address": "97.65.251.242",
"caller_country_code": "US",
"caller_location": "30.2971,-97.7862"
},
"modified": {
"user": "admin@example.com",
"timestamp": "2022-01-19T18:36:20.874Z",
"client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
"client_inet_address": "97.65.251.242",
"client_country_code": "US",
"client_location": "30.2971,-97.7862",
"caller_inet_address": "97.65.251.242",
"caller_country_code": "US",
"caller_location": "30.2971,-97.7862"
},
"line1": "5400 Burnet",
"city": "Austin",
"state_or_province": "TX",
"postal_code": "78756",
"country_code": "US",
"preferred": false,
"type": "address"
}
],
"email_addresses": [
{
"id": "eml_Pocc0DLipfEZio0qA9f9p",
"created": {
"user": "admin@example.com",
"timestamp": "2022-01-19T18:17:20.305Z",
"client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
"client_inet_address": "97.65.251.242",
"client_country_code": "US",
"client_location": "30.2971,-97.7862",
"caller_inet_address": "97.65.251.242",
"caller_country_code": "US",
"caller_location": "30.2971,-97.7862"
},
"modified": {
"user": "admin@example.com",
"timestamp": "2022-01-19T18:17:20.305Z",
"client_id": "41a2c1019e63db49b0efe23b16fea19c685d7c896657470174a1cc91b54cddc7",
"client_inet_address": "97.65.251.242",
"client_country_code": "US",
"client_location": "30.2971,-97.7862",
"caller_inet_address": "97.65.251.242",
"caller_country_code": "US",
"caller_location": "30.2971,-97.7862"
},
"address": "ckent@example.com",
"preferred": true,
"type": "email_address"
}
],
"first_name": "Clark",
"last_name": "Kent",
"display_name": "Clark Kent",
"type": "person"
}
```
--------------------------------
### Example POST Request to Sign Up Merchant Application
Source: https://developers.8am.com/reference/api
This snippet demonstrates how to make a POST request to the AffiniPay API to sign up a merchant application. It includes the endpoint, required headers, and a sample JSON payload.
```curl
curl -X POST -H "Content-Type:application/json" -H "Authorization: Bearer " https://secure.affinipay.com/api/v1/merchant_applications/sign_up
{
"reference": "1941",
"email": "diana@example.com",
"plan": "superplan"
}
```
--------------------------------
### Event Data Structure Example
Source: https://developers.8am.com/reference/api
This JSON object represents the structure of an event returned by the 8am Gateway's 'Get Event by ID' endpoint. It includes event metadata like ID, creation timestamp, and type, along with detailed event-specific data. Note that sensitive payment details are not included.
```json
{
"id" : "DYEDsGU_RgWjwnY5cTPMew",
"created" : "2016-10-25T17:41:41.959Z",
"type" : "transaction.authorized",
"data" : {
"id" : "m7wPNJgUT4uHNRoSdUpTnA",
"created" : "2016-10-25T17:41:41.938Z",
"modified" : "2016-10-25T17:41:41.938Z",
"account_id" : "8IO47jzCEeOfvhLxg70sog",
"status" : "AUTHORIZED",
"amount" : 100,
"currency" : "USD",
"auto_capture" : true,
"amount_refunded" : 0,
"authorization_code": "H3PKFH",
"type" : "CHARGE",
"method" : {
"name" : "Some Customer",
"address1" : "123 Main",
"postal_code" : "78730",
"type" : "card",
"number" : "************4242",
"fingerprint" : "GunPelYVthifNV63LEw1",
"card_type" : "VISA",
"exp_month" : 10,
"exp_year" : 2027,
"cvv" : "***"
}
}
}
```
--------------------------------
### Example Response for Merchant Application Sign Up
Source: https://developers.8am.com/reference/api
This snippet shows a typical JSON response received after successfully signing up a merchant application via the AffiniPay API. It includes the merchant application ID and a redirect URI.
```json
{
"merchant_application": {
"id": 1941
},
"redirect_uri": "https://secure.affinipay.com/sso/merchant_applications/registrations?token=512...>"
}
```
--------------------------------
### Example: Testing Relayed IP Addresses with curl
Source: https://developers.8am.com/reference/api
Demonstrates how to test relayed IP addresses against Merchant client restrictions using a curl command. This involves setting the 'X-Relayed-IP-Address' header to simulate a client's IP for policy checks.
```shell
curl -H "X-Relayed-IP-Address: 127.0.0.1" ...
```
--------------------------------
### Get a Specific Bank
Source: https://developers.8am.com/reference/api
Retrieves a previously saved bank by its ID. The request is a GET to /v1/banks/{bankId}. The response is a JSON representation of the bank with sensitive properties masked.
```bash
curl -X GET --user secret_key: https://api.8am.com/v1/banks/vU42KZWhTd2iiGLhjfJR6A
```
--------------------------------
### POST /merchant_applications/sign_up
Source: https://developers.8am.com/reference/api
Initiates the branded sign-up flow for a new merchant application. This endpoint creates a new merchant_application object and submits it to 8am for review. The request URL must be tailored to the specific product being integrated (AffiniPay, ClientPay, CPACharge, or LawPay).
```APIDOC
## POST /merchant_applications/sign_up
### Description
Creates a new merchant_application object using the branded sign-up flow and submits it to 8am for review and approval. The request URL must correspond to the product you are integrating into your application.
### Method
POST
### Endpoint
`https://secure.[product].com/api/v1/merchant_applications/sign_up`
(Replace `[product]` with `affinipay`, `clientpay`, `cpacharge`, or `lawpay`)
### Parameters
#### Request Body
**Required Parameters:**
- **reference** (string) - The unique ID for the user in the partner's system.
- **email** (string) - The user's email.
- **plan** (string) - The identifier for your plan within the 8am system. This plan will be created and an ID provided.
**Optional Parameters:**
- **first_name** (string) - First name of the person associated with the merchant application.
- **last_name** (string) - Last name of the person associated with the merchant application.
- **business_name** (string) - The business's legal name. This must match what is on record with the IRS.
- **business_address1** (string) - The business's mailing address.
- **business_address2** (string) - Additional address field.
- **business_city** (string) - The city where the business is located.
- **business_state** (string) - The state where the business is located.
- **business_zip_code** (string) - The business's postal ZIP code.
- **business_phone** (string) - The business's primary contact number.
- **business_country** (string) - The 2-letter ISO 3166 country code for the country where the business is located.
- **industry_code** (integer) - The business's Standard Industrial Classification (SIC) code (e.g., 8111 – Legal Services).
- **goods_and_services** (string) - For LawPay integration, send "Legal Fees". Contact 8am for other integrations.
- **has_dba** (boolean) - Indicates whether a Doing Business As (DBA) name has been registered for the business; default is false.
- **dba_name** (string) - The business's registered Doing Business As (DBA) name (optional if has_dba is false).
- **dba_address1** (string) - The mailing address of the business with a registered Doing Business As (DBA) name (optional if has_dba is false).
- **dba_address2** (string) - Additional address field (optional if has_dba is false).
- **dba_city** (string) - The city where the business with a registered Doing Business As (DBA) name is located (optional if has_dba is false).
- **dba_state** (string) - The state where the business with a registered Doing Business As (DBA) name is located (two-letter state code) (optional if has_dba is false).
- **dba_zip_code** (string) - The postal ZIP code of the business with a registered Doing Business As (DBA) name (optional if has_dba is false).
- **dba_phone** (string) - The primary contact number of the business with a registered Doing Business As (DBA) name (optional if has_dba is false).
- **structure** (string) - The business's structure. Accepts abbreviations: SO, AE, G, CP, CU, P, TE, SM, MM, CA, LP, PO.
- **business_type** (string) - The type of industry. Accepts abbreviations: R, I, M, H, F.
- **years_in_business** (string) - Number years the business has been in operation.
- **business_website** (string) - The business's website.
- **past_bankruptcy** (boolean) - Indicates whether the business has been through bankruptcy proceedings in the past.
- **bankruptcy_date** (date) - The date the bankruptcy was finalized.
- **owner_first_name** (string) - The business owner's legal first name.
- **owner_last_name** (string) - The business owner's legal last name.
- **owner_title** (string) - The business owner's title. Accepts: President, V.President, Owner, Partner, Manager, Treasurer, Secretary, Exec.Director.
### Request Example
```json
{
"reference": "partner_ref_123",
"email": "user@example.com",
"plan": "your_plan_id",
"first_name": "John",
"last_name": "Doe",
"business_name": "Example Corp",
"business_address1": "123 Main St",
"business_city": "Anytown",
"business_state": "CA",
"business_zip_code": "90210",
"business_country": "US",
"industry_code": 8111,
"goods_and_services": "Legal Fees",
"has_dba": true,
"dba_name": "Example DBA",
"owner_first_name": "Jane",
"owner_last_name": "Doe",
"owner_title": "Owner"
}
```
### Response
#### Success Response (200)
- **merchant_application_id** (string) - The unique identifier for the created merchant application.
- **status** (string) - The current status of the merchant application.
#### Response Example
```json
{
"merchant_application_id": "app_abc123",
"status": "pending_review"
}
```
```
--------------------------------
### Get Current Merchant - cURL Request
Source: https://developers.8am.com/reference/api
This snippet demonstrates how to make a GET request to the /v1/merchant endpoint using cURL. It requires authentication with a secret key. The response will contain the merchant's details.
```shell
curl -X GET --user secret_key: https://api.8am.com/v1/merchant
```
--------------------------------
### Credit Funds to a Bank Account via API
Source: https://developers.8am.com/reference/api
This example shows how to credit funds to a customer's bank account using the 8am API. It requires the amount and bank account details, including routing and account numbers, in a JSON POST request. The API authorizes the transfer and returns credit information.
```bash
curl -X POST -H "Content-Type:application/json" --user secret_key: https://api.8am.com/v1/credits -d '
{
"amount": "18000",
"method": {
"type": "bank",
"routing_number": "000000013",
"account_number": "1100000003",
"account_type": "SAVINGS"
"name": "Customer Inc",
"account_holder_type": "business"
}
}'
```
--------------------------------
### POST /api/v1/merchant_applications/sign_up
Source: https://developers.8am.com/reference/api
This endpoint is used to initiate the merchant application process. It requires a reference, email, and plan to create a new merchant application.
```APIDOC
## POST /api/v1/merchant_applications/sign_up
### Description
Initiates the merchant application process by creating a new merchant application with the provided details.
### Method
POST
### Endpoint
https://secure.affinipay.com/api/v1/merchant_applications/sign_up
### Parameters
#### Request Body
- **reference** (string) - Required - A unique identifier for the application.
- **email** (string) - Required - The email address associated with the merchant.
- **plan** (string) - Required - The subscription plan for the merchant.
### Request Example
```json
{
"reference": "1941",
"email": "diana@example.com",
"plan": "superplan"
}
```
### Response
#### Success Response (200)
- **merchant_application** (object) - Contains details about the created merchant application.
- **id** (integer) - The unique identifier of the merchant application.
- **redirect_uri** (string) - The URI to redirect the user for further steps in the application process.
#### Response Example
```json
{
"merchant_application": {
"id": 1941
},
"redirect_uri": "https://secure.affinipay.com/sso/merchant_applications/registrations?token=512...>"
}
```
```