The operations described in this section enable you to perform accounts receivable operations.

Get account balance

GET /v2/accounts/{ran}/balance

Get the account balance.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI string (Required)	A billing account number.
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Value: application/json

This operation does not accept a request body.

Response

Example Get account balance: JSON response

{
  "balance": {
    "amountDue": "1500.25",
    "currentBalance": "1510.75",
    "pastDue": "10.5",
    "currency": "USD",
    "unbilledCharges": "692.5"
  }
}

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer

Get billing summary

GET /v2/accounts/{ran}/billing-summary

Get the account billing summary.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI string (Required)	A billing account number.
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Value: application/json

This table shows the query parameters for the request:

Name	Type	Description
limit	Integer	An integer between 1 and 200 that specifies the number of records to return. The default limit is 25 records. To learn more about pagination rules, refer to section Paginated Collections.
marker	Integer	An integer between 0 and the last item of the result list.
startDate	Date	A string that specifies the start date of the transactions. When not provided, it defaults to two years in the past, from the current day. Billing summary responses are restricted for the time period beginning at this date. Dates must be expressed in UTC. The date format is ISO 8601 YYYY-MM-DD.
endDate	Date	A string that specifies the end date of the transactions. The end date has to be after the start date. When not provided, it defaults to the current date. Billing summary responses are restricted for the time period ending at this date. Dates must be expressed in UTC. The start date must be less than or equal to the end date. The date format is ISO 8601 YYYY-MM-DD.

This operation does not accept a request body.

Response

Example Billing summary: JSON response

{
  "billingSummary": {
    "item": [
      {
        "id": "cfc42488-0ce2-4068-b39a-1892438f418f",
        "openBalance": "23.55",
        "tranRefNum": "A1-12345",
        "date": "2013-05-26T16:32:52.000-05:00",
        "amount": "296.75",
        "status": "OPEN",
        "type": "CREDIT",
        "link": [
          {
            "rel": "self",
            "href": "https://billing.api.rackspacecloud.com/v2/accounts/{ran}/adjustments/{adjustmentId}"
          }
        ]
      },
      {
        "id": "d19b0bfa-862d-4bbe-a38c-c8cac997f083",
        "openBalance": "23.55",
        "tranRefNum": "B1-12345",
        "date": "2013-05-26T15:32:52.000-05:00",
        "amount": "296.75",
        "coverageEndDate": "2018-07-28T00:00:00Z",
        "coverageStartDate": "2018-06-28T00:00:00Z",
        "status": "OPEN",
        "type": "INVOICE",
        "link": [
          {
            "rel": "self",
            "href": "https://billing.api.rackspacecloud.com/v2/accounts/{ran}/invoices/{invoiceId}"
          }
        ]
      },
      {
        "id": "0d81bfc6-91bf-4c60-9821-4ad2e581bfc6",
        "openBalance": "101.01",
        "tranRefNum": "A1-4503",
        "date": "2018-07-05T05:15:44Z",
        "amount": "101.01",
        "status": "OPEN",
        "type": "REFUND",
        "link": [
          {
            "href": "https://billing.api.rackspacecloud.com/v2/accounts/${ran}/refunds/{refundId}",
            "rel": "self"
          }
        ]
      },
      {
        "id": "9043be0f-a0a7-4d8a-b165-bb722bc19243",
        "openBalance": "23.55",
        "tranRefNum": "P1-123456123",
        "date": "2013-06-01T21:32:52.000-05:00",
        "amount": "355.50",
        "status": "CLOSED",
        "type": "PAYMENT",
        "link": [
          {
            "rel": "self",
            "href": "https://billing.api.rackspacecloud.com/v2/accounts/{ran}/payments/{paymentId}"
          }
        ]
      }
    ],
    "total": 12345,
    "link": [
      {
        "rel": "prev",
        "href": "https://billing.api.rackspacecloud.com/v2/accounts/{ran}/billing-summary?marker=30&limit=15"
      },
      {
        "rel": "next",
        "href": "https://billing.api.rackspacecloud.com/v2/accounts/{ran}/billing-summary?marker=45&limit=15"
      }
    ],
    "currency": "USD",
    "accountNumber": "{ran}"
  }
}

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer

This table shows the possible status values for each transaction type:

Transaction type	Status
Invoice	OPEN, CLOSED
Credit or debit	OPEN, CLOSED
Payment	PENDING, CLOSED
Refund	OPEN, PENDING, CLOSED, NONE
Reversal	OPEN, CLOSED

Get invoice

GET /v2/accounts/{ran}/invoices/{invoiceId}

Get the invoice identified by the invoiceID.

This call returns an HTTP 202 error when the document is not yet ready for the clients to consume. This code indicates that the document is temporarily unavailable and that clients should try again later. Valid values for invoiceId include B1, B1-PO, and S1.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI string (Required)	A billing account number.
{invoiceId}	URI string (Required)	An invoice identifier.
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Values: application/json, application/pdf

This operation does not accept a request body.

Response

Example Get invoice: JSON response

{
  "invoice": {
    "date": "2013-05-01T16:32:52.000-05:00",
    "accountName": "ESPN Sports",
    "invoiceSubTotal": "600.02",
    "dueDate": "2013-04-30T19:00:00.000-05:00",
    "taxTotal": "10.01",
    "consolidatedAccountNumber": "EBS123456",
    "coverageEndDate": "2013-04-30T16:32:52.000-05:00",
    "invoiceTotal": "600.01",
    "coverageStartDate": "2013-04-01T16:32:52.000-05:00",
    "tranRefNum": "B1-123456785",
    "discountTotal": "20.02",
    "sellerOfRecordInfo": "Rackspace US, Inc. P.O. Box 730759 Dallas,",
    "currency": "USD",
    "id": "7dc53df5-703e-49b3-8670-b1c468f47f1f",
    "paymentTerms": "Due upon receipt",
    "invoiceSection": [
      {
        "invoiceItem": [
          {
            "itemType": "PRODUCT_CHARGES",
            "itemAmount": "21.61",
            "name": "Cloud Servers",
            "id": "0f35a016-2ea1-4ea3-8399-0fe3601d5bac"
          },
          {
            "itemType": "SUPPORT_CHARGES",
            "itemAmount": "828.23",
            "name": "Managed Infrastructure",
            "id": "0439a07e-6f9b-439e-9256-c051b3ab7a12"
          },
          {
            "itemType": "OTHER_CHARGES",
            "itemAmount": "20.01",
            "name": "Bulk File importing",
            "id": "0439a07e-6f9b-439e-9256-c051b3ab7a1f"
          }
        ],
        "sectionId": "{ran}",
        "sectionType": "ACCOUNT_NUMBER"
      }
    ],
    "invoiceContact": [
      {
        "address": {
          "zip": "75373-0759",
          "country": "United States",
          "city": "Austin",
          "addressLine1": "64 Austin HWY",
          "state": "TX"
        },
        "name": "Mary Silva",
        "contactType": "BILLER"
      },
      {
        "address": {
          "zip": "78218",
          "country": "United States",
          "city": "San Antonio",
          "addressLine1": "320 Basse Rd",
          "state": "TX"
        },
        "name": "ESPN Sports",
        "contactType": "BILL_TO_PRIMARY"
      }
    ],
    "status": "OPEN"
  }
}

Sample JSON that is a purchase order:

If the invoiceId in the request is a PO number, the following partial response shows the portions that differ for this request, where the tranRefNum starts with B1-PO- and a poNumber is present.

{
  "invoice": {
    ...
    ...
    "tranRefNum": "B1-PO-123456785",
    "poNumber": "2D2F5V58F",
    ...
    ...
  }
}

Sample JSON that is a statement:

If the invoiceId in the request is a statement, the following partial response shows the portions that differ for this request, where the tranRefNum starts with S1-.

{
  "invoice": {
    ...
    ...
    ...
    tranRefNum": "S1-123456785",
    ...
    ...
    ...
  }
}

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
202	Accepted	The document is not yet ready for the clients to consume.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer

Get current invoice

GET /v2/accounts/{ran}/invoices/latest

Get the latest (most recent or current) invoice. The operation returns the format of the invoice based on the Accept header passed.

This call returns an HTTP 202 error when the document is not yet ready for the clients to consume. This code indicates that the document is temporarily unavailable and that clients should try again.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI String (Required)	A billing account number.
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Value: application/json, application/pdf

This operation does not accept a request body.

Response

Example Get current invoice: JSON response

{
  "invoice": {
    "date": "2013-05-01T16:32:52.000-05:00",
    "accountName": "ESPN Sports",
    "invoiceSubTotal": "600.02",
    "dueDate": "2013-04-30T19:00:00.000-05:00",
    "taxTotal": "10.01",
    "consolidatedAccountNumber": "EBS123456",
    "coverageEndDate": "2013-04-30T16:32:52.000-05:00",
    "invoiceTotal": "600.01",
    "coverageStartDate": "2013-04-01T16:32:52.000-05:00",
    "tranRefNum": "B1-123456785",
    "discountTotal": "20.02",
    "invoiceSection": [
      {
        "invoiceItem": [
          {
            "itemType": "PRODUCT_CHARGES",
            "itemAmount": "21.61",
            "name": "Cloud Servers",
            "id": "0f35a016-2ea1-4ea3-8399-0fe3601d5bac"
          },
          {
            "itemType": "SUPPORT_CHARGES",
            "itemAmount": "828.23",
            "name": "Managed Infrastructure",
            "id": "0439a07e-6f9b-439e-9256-c051b3ab7a12"
          },
          {
            "itemType": "OTHER_CHARGES",
            "itemAmount": "20.01",
            "name": "Bulk File importing",
            "id": "0439a07e-6f9b-439e-9256-c051b3ab7a1f"
          }
        ],
        "sectionId": "{ran}",
        "sectionType": "ACCOUNT_NUMBER"
      }
    ],
    "sellerOfRecordInfo": "Rackspace US, Inc. P.O. Box 730759 Dallas,",
    "currency": "USD",
    "id": "7dc53df5-703e-49b3-8670-b1c468f47f1f",
    "paymentTerms": "Due upon receipt",
    "invoiceContact": [
      {
        "address": {
          "zip": "75373-0759",
          "country": "United States",
          "city": "Austin",
          "addressLine1": "64 Austin HWY",
          "state": "TX"
        },
        "name": "Mary Silva",
        "contactType": "BILLER"
      },
      {
        "address": {
          "zip": "78218",
          "country": "United States",
          "city": "San Antonio",
          "addressLine1": "320 Basse Rd",
          "state": "TX"
        },
        "name": "ESPN Sports",
        "contactType": "BILL_TO_PRIMARY"
      }
    ],
    "status": "OPEN"
  }
}

Sample JSON where the current invoice is a purchase order:

If the billingAccount has the latest invoice with the PO, the following partial response shows the portions that differ. The tranRefNum starts with B1-PO and the poNumber is included.

{
  "invoice": {
    ...
    ...
    ...
    "tranRefNum": "B1-PO-123456785",
    "poNumber": "2D2F5V58F",
    ...
    ...
    ...
  }
}

Sample JSON where the current invoice is a statement:

If the billingAccount has the latest invoice as statement, the following partial response shows the portions that differ. The tranRefNum starts with S1-.

{
  "invoice": {
    ...
    ...
    ...
    "tranRefNum": "S1-123456785",
    ...
    ...
    ...
  }
}

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
202	Accepted	The document is not yet ready for the clients to consume.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer

Get detailed billing report for an invoice

GET /v2/accounts/{ran}/invoices/{invoiceId}/detail

Get a detailed billing report for an invoice. This call also provides additional details that give more visibility into the invoice.

This call returns an HTTP 202 error when the document is not yet ready for the clients to consume. This code indicates that the document is temporarily unavailable and that clients should try again.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI string (Required)	A billing account number.
{invoiceId}	URI string (Required)	An invoice identifier.
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Value: text/csv

This operation does not accept a request body.

Response

This operation returns CSV content (text/csv) as response.

Example Get detailed billing report for an invoice: CSV

Sample csv response

ACCOUNT_NO,BILL_NO,BILL_START_DATE,BILL_END_DATE,SERVICE_TYPE,EVENT_TYPE,EVENT_START_DATE,EVENT_END_DATE,IMPACT_TYPE,QUANTITY,UOM,RATE,AMOUNT,USAGE_RECORD_ID,DC_ID,REGION_ID,RES_ID,RES_NAME,ATTRIBUTE_1,ATTRIBUTE_2,ATTRIBUTE_3
{ran},{billNumber},12/12/2014 0:00,1/12/2015 0:00,Cloud Sites,Other Charges - Subscription,1/12/2015 0:00,1/12/2015 0:00,CHARGE,1,,100/mo,100,,,,,,,,
{ran},{billNumber},12/12/2014 0:00,1/12/2015 0:00,ACCOUNT,TAX,1/11/2015 23:59,1/11/2015 23:59,State Tax,100,,,0,,,,,,,,
{ran},{billNumber},12/12/2014 0:00,1/12/2015 0:00,ACCOUNT,TAX,1/11/2015 23:59,1/11/2015 23:59,County Tax,100,,,0,,,,,,,,
{ran},{billNumber},12/12/2014 0:00,1/12/2015 0:00,ACCOUNT,TAX,1/11/2015 23:59,1/11/2015 23:59,Local Sales Tax,100,,,0,,,,,,,,

The following list shows some columns to note in the downloaded invoice.

ACCOUNT_NO
BILL_NO
BILL_START_DATE
BILL_END_DATE
SERVICE_TYPE : The services used in the billing period.
EVENT_TYPE : The division of billing charges for each product or other charges if applicable, along with the tax amount.

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
202	Accepted	The document is not yet ready for the clients to consume.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer

Check for detailed billing report for an invoice

HEAD /v2/accounts/{ran}/invoices/{invoiceId}/detail

Checks whether the invoice can have a billing report. You should be prepared to handle a badRequest (400) fault for invoices that are not eligible to have reports.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI string (Required)	A billing account number.
{invoiceId}	URI string (Required)	An invoice identifier.
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Values: application/json

This operation does not accept a request body.

Response

This operation does not return a response body.

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer

Get adjustment

GET /v2/accounts/{ran}/adjustments/{adjustmentId}

Get the adjustment details identified by the adjustmentId.

This call returns an HTTP 202 when the document is not yet ready for the clients to consume. This code indicates that the document is temporarily unavailable and that clients should try again.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI string (Required)	A billing account number.
{adjustmentId}	URI string (Required)	An adjustment identifier.
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Values: application/json, application/pdf

This operation does not accept a request body.

Response

Example Get adjustment: JSON response

{
  "adjustment": {
    "itemReferences": {
      "itemReference": [
        {
          "tranRefNum": "A1-1234567",
          "amountApplied": "20.0",
          "tranDate": "2013-05-26T16:32:52.000-05:00",
          "id": "68bcaeb0-d486-4637-a6c8-846d401be419",
          "type": "DEBIT_ADJ"
        }
      ]
    },
    "amount": "22.65",
    "tranRefNum": "A1-1234564",
    "currency": "USD",
    "reasonCode": "Uptime SLA",
    "tranDate": "2013-08-26T16:32:52.000-05:00",
    "id": "6e0004cb-f0bd-4085-8419-5ee3fc980aad",
    "type": "CREDIT",
    "status": "POSTED"
  }
}

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
202	Accepted	The document is not yet ready for the clients to consume.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer

Get payment

GET /v2/accounts/{ran}/payments/{paymentId}

Get the payment identified by the paymentId.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI string (Required)	A billing account number.
{paymentId}	URI string (Required)	A payment identifier.
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Values: application/json

This operation does not accept a request body.

Response

Example Get payment detail by ID for credit card (CC) payment: JSON response

{
  "payment": {
    "amount": "-22.65",
    "gatewayTxRefNum": "4C3213241331117CD265DE7ADA3967A15218542B",
    "methodId": "urn:uuid:fa093563-73db-4fe4-8f3a-def53dde8f5d",
    "submissionDate": "2013-05-26T16:32:52.000-05:00",
    "transactionId": "T1,123456,1",
    "itemReferences": {
      "itemReference": [
        {
          "tranRefNum": "B1-1234567",
          "amountApplied": "10.0",
          "tranDate": "2013-04-26T07:32:52.000-05:00",
          "id": "12bcaeb0-d486-4637-a6c8-846d401be000",
          "type": "INVOICE"
        },
        {
          "tranRefNum": "A1-1234567",
          "amountApplied": "5.0",
          "tranDate": "2013-05-26T16:06:22.000-05:00",
          "id": "34bcaeb0-d486-4637-a6c8-846d401be555",
          "type": "DEBIT_ADJ"
        }
      ]
    },
    "tranRefNum": "P1-1234564",
    "methodType": "CREDITCARD",
    "currency": "USD",
    "paymentMethodDetails": {
      "paymentCard": {
        "cardType": "VISA",
        "ccExpiry": "12/16",
        "ccLast4": "6007",
        "ccHolderName": "Joe Doe"
      }
    },
    "id": "6e81bfc6-81bf-4c68-8ae2-7ad2e58641f6",
    "responseMessage": "Approved",
    "status": "CLOSED"
  }
}

Sample JSON for payment with Automated Clearing House:

If the paymentId in the request is an ACH payment type (ACH), the following partial response shows the portions that differ for this request.

{
  "payment": {
    ...
    ...
    ...
    "methodType": "ACH",
    "currency": "USD",
    "paymentMethodDetails": {
      "electronicCheck": {
        "routingNumber": "001234567",
        "accountNumber": "0000",
        "accountHolderName": "Check Rich"
      }
    },
    "id": "6e81bfc6-81bf-4c68-8ae2-7ad2e58641f6",
    "responseMessage": "Approved",
    "status": "CLOSED"
  }
}

Sample JSON for payment with UK Direct Debit:

If the paymentId in the request is a UK Direct Debit (DD) payment type, the following partial response shows the portions that differ for this request.

{
  "payment": {
    ...
    ...
    ...
    "methodType": "UKDD",
    "currency": "GBP",
    "paymentMethodDetails": {
      "ukDirectDebit": {
        "bankSortCode": "606006",
        "bankAccountNumber": "XXXXXXXX6789",
        "accountHolderName": "Edward Heath"
      }
    },
    "id": "6e81bfc6-81bf-4c68-8ae2-7ad2e58641f6",
    "status": "CLOSED"
  }
}

Sample JSON for payment with Netherlands Single Euro Payments area:

If the paymentId in the request is a Netherlands Single Euro Payments area (NL SEPA) payment type, the following partial response shows the portions that differ for this request.

{
  "payment": {
    ...
    ...
    ...
    "methodType": "NLSEPA",
    "currency": "EUR",
    "paymentMethodDetails": {
      "nlSEPA": {
        "iban": "XXXXXXXXXXX00057",
        "bic": "HANDFIHH"
      }
    },
    "id": "6e81bfc6-81bf-4c68-8ae2-7ad2e58641f6",
    "responseMessage": "Approved",
    "status": "CLOSED"
  }
}

Sample JSON for payment with Lockbox/Check:

If the paymentId in the request is a Lockbox/Check payment type, the following partial response shows the portions that differ for this request.

{
  "payment": {
   ...
   ...
   ...
    "methodType": "LOCKBOX",
    "currency": "USD",
    "paymentMethodDetails": {
      "lockboxPayment": {
        "routingNumber": "001234567",
        "checkNumber": "000111222",
        "lockboxNumber": "1234567",
        "lockboxPaymentMethodType": "CHECK",
        "accountNumber": "0000"
      }
    },
    "id": "6e81bfc6-81bf-4c68-8ae2-7ad2e58641f6",
    "status": "CLOSED"
  }
}

Sample JSON for payment with Lockbox/Wire:

If the paymentId in the request is a Lockbox/Wire payment type, the following partial response shows the portions that differ for this request.

{
  "payment": {
   ...
   ...
   ...
    "methodType": "LOCKBOX",
    "currency": "USD",
    "paymentMethodDetails": {
      "lockboxPayment": {
        "routingNumber": "001234567",
        "wireTransferId": "000111222",
        "lockboxNumber": "1234567",
        "lockboxPaymentMethodType": "WIRE",
        "accountNumber": "0000"
      }
    },
    "id": "6e81bfc6-81bf-4c68-8ae2-7ad2e58641f6",
    "status": "CLOSED"
  }
}

Sample JSON for payment with Lockbox/ACH:

If the paymentId in the request is a Lockbox/ACH payment type, the following partial response shows the portions that differ for this request.

{
  "payment": {
   ...
   ...
   ...
    "methodType": "LOCKBOX",
    "currency": "USD",
    "paymentMethodDetails": {
      "lockboxPayment": {
        "routingNumber": "001234567",
        "lockboxNumber": "1234567",
        "lockboxPaymentMethodType": "ACH",
        "accountNumber": "0000",
        "authenticationNumber": "000111222"
      }
    },
    "id": "6e81bfc6-81bf-4c68-8ae2-7ad2e58641f6",
    "status": "CLOSED"
  }
}

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer

Get list of payments for an invoice

GET /v2/accounts/{ran}/invoices/{invoiceId}/payments

Returns a list of payments related to an invoice identified by invoiceId.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI string (Required)	A billing account number.
{invoiceId}	URI string (Required)	An invoice identifier.
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Values: application/json

This operation does not accept a request body.

Response

Example Get list of payments for an invoice: JSON response

{
  "payments": {
    "payment": [
      {
        "amount": "-22.65",
        "gatewayTxRefNum": "4C3213241331117CD265DE7ADA3967A15218542B",
        "methodId": "urn:uuid:fa093563-73db-4fe4-8f3a-def53dde8f5d",
        "submissionDate": "2013-05-26T16:32:52.000-05:00",
        "transactionId": "T1,123456,1",
        "itemReferences": {
          "itemReference": [
            {
              "tranRefNum": "B1-1234567",
              "amountApplied": "10.0",
              "tranDate": "2013-04-26T07:32:52.000-05:00",
              "id": "12bcaeb0-d486-4637-a6c8-846d401be000",
              "type": "INVOICE"
            }
          ]
        },
        "tranRefNum": "P1-1234564",
        "methodType": "CREDITCARD",
        "currency": "USD",
        "paymentMethodDetails": {
          "paymentCard": {
            "cardType": "VISA",
            "ccExpiry": "12/16",
            "ccLast4": "6007",
            "ccHolderName": "Joe Doe"
          }
        },
        "id": "6e81bfc6-81bf-4c68-8ae2-7ad2e58641f6",
        "responseMessage": "Approved",
        "status": "CLOSED"
      },
      {
        "amount": "-22.65",
        "gatewayTxRefNum": "4C3213241331117CD265DE7ADA3967A15218542B",
        "methodId": "urn:uuid:fa093563-73db-4fe4-8f3a-def53dde8f5d",
        "submissionDate": "2013-05-26T16:32:52.000-05:00",
        "transactionId": "T1,123450,1",
        "itemReferences": {
          "itemReference": [
            {
              "tranRefNum": "B1-1234567",
              "amountApplied": "17.65",
              "tranDate": "2013-04-26T07:32:52.000-05:00",
              "id": "12bcaeb0-d486-4637-a6c8-846d401be000",
              "type": "INVOICE"
            },
            {
              "tranRefNum": "D1-1234567",
              "amountApplied": "5.0",
              "tranDate": "2013-05-26T16:06:22.000-05:00",
              "id": "34bcaeb0-d486-4637-a6c8-846d401be555",
              "type": "DEBIT_ADJ"
            }
          ]
        },
        "tranRefNum": "P1-1211111",
        "methodType": "ACH",
        "currency": "USD",
        "paymentMethodDetails": {
          "electronicCheck": {
            "routingNumber": "001234567",
            "accountNumber": "0000",
            "accountHolderName": "Check Rich"
          }
        },
        "id": "6e81bfc6-81bf-4c68-8ae2-7ad2e58641f6",
        "status": "CLOSED"
      }
    ],
    "link": [],
    "total": "6"
  }
}

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer

Get refund

GET /v2/accounts/{ran}/refunds/{refundId}

Get a refund identified by the refundId.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI string (Required)	A billing account number.
{refundId}	URI string (Required)	A refund identifier
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Values: application/json

This operation does not accept a request body.

Response

Example Get refund by ID (check): JSON response

{
  "refund": {
    "amount": "10.45",
    "gatewayTxRefNum": "5098B66B8741F2E4A38B24F103150B3AEA8A530E",
    "methodId": "urn:uuid:fa093563-73db-4fe4-8f3a-def53dde8f5d",
    "itemReferences": {
      "itemReference": [
        {
          "tranRefNum": "P1-1234567",
          "amountApplied": "20.0",
          "tranDate": "2011-04-26T07:32:52.000-05:00",
          "id": "12bcaeb0-d486-4637-a6c8-846d401be000",
          "type": "PAYMENT"
        }
      ]
    },
    "tranRefNum": "A1-1234561",
    "methodType": "CHECK",
    "currency": "USD",
    "paymentMethodDetails": {
      "checkPayment": {
        "checkNumber": "000111222",
        "accountNumber": "0000"
      }
    },
    "tranDate": "2013-05-26T16:32:52.000-05:00",
    "id": "cfc42488-0ce2-4068-b39a-1892438f418f",
    "reasonCode": "Check refund",
    "status": "CLOSED"
  }
}

Sample JSON for refund with ACH:

If the refundId in the request is a ACH payment type, the following partial response shows the portions that differ for this request.

{
  "refund": {
    ...
    ...
    ...
    "tranRefNum": "A1-1234561",
    "methodType": "ACH",
    "currency": "USD",
    "paymentMethodDetails": {
      "electronicCheck": {
        "routingNumber": "001234567",
        "accountType": "PERSONAL_CHECKING",
        "accountNumber": "0000",
        "accountHolderName": "Check Rich"
      }
    },
    ...
    ...
    ...
  }
}

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer

Get reversal

GET /v2/accounts/{ran}/reversals/{reversalId}

Get the reversal identified by the reversalId.

Request

The request has the following URI and header parameters:

Name	Type	Description
{ran}	URI string (Required)	A billing account number.
{reversalId}	URI string (Required)	A reversal identifier.
X-Auth-Token	Header string (Required)	A valid authentication token associated with the particular role.
Accept	Header string	Values: application/json

This operation does not accept a request body.

Response

Example Get payment reversal by ID for CC payment: JSON response

{
  "reversal": {
    "amount": "10.45",
    "itemReferences": {
      "itemReference": [
        {
          "tranRefNum": "P1-1234567",
          "amountApplied": "20.0",
          "tranDate": "2011-04-26T07:32:52.000-05:00",
          "id": "12bcaeb0-d486-4637-a6c8-846d401be000",
          "type": "PAYMENT"
        }
      ]
    },
    "tranRefNum": "P1-1234567",
    "methodType": "CREDITCARD",
    "paymentId": "b153650f-a293-41f1-988d-1b7cf7d3fbed",
    "currency": "USD",
    "paymentMethodDetails": {
      "paymentCard": {
        "cardType": "VISA",
        "ccExpiry": "12/16",
        "ccLast4": "6007",
        "ccHolderName": "Joe Doe"
      },
      "paymentId": "urn:uuid:696c40a0-c3e7-11e2-8b8b-0800200c9a66"
    },
    "tranDate": "2013-05-26T16:32:52.000-05:00",
    "id": "6e0004cb-f0bd-4085-8419-5ee3fc980aad",
    "reasonCode": "Merchant initiated chargeback",
    "status": "APPROVED"
  }
}

Sample JSON for reversal with ACH:

If the reversalId in the request is a ACH payment type, the following partial response shows the portions that differ for this request.

{
  "reversal": {
    ...
    ...
    ...
    "methodType": "ACH",
    "currency": "USD",
    "paymentMethodDetails": {
      "electronicCheck": {
        "routingNumber": "001234567",
        "accountType": "PERSONAL_CHECKING",
        "accountNumber": "0000",
        "accountHolderName": "Check Rich"
      }
    },
    ...
    ...
    ...
  }
}

Sample JSON for reversal with Lockbox/Check:

If the reversalId in the request is a Lockbox/Check payment type, the following partial response shows the portions that differ for this request.

{
  "reversal": {
    ...
    ...
    ...
    "methodType": "LOCKBOX",
    "currency": "USD",
    "paymentMethodDetails": {
      "lockboxPayment": {
        "routingNumber": "001234567",
        "checkNumber": "000111222",
        "lockboxNumber": "1234567",
        "lockboxPaymentMethodType": "CHECK",
        "accountNumber": "0000"
      }
    },
    ...
    ...
    ...
  }
}

Sample JSON for reversal with Lockbox/ACH:

If the reversalId in the request is a Lockbox/ACH payment type, the following partial response shows the portions that differ for this request.

{
  "reversal": {
    ...
    ...
    ...
    "methodType": "LOCKBOX",
    "paymentId": "b153650f-a293-41f1-988d-1b7cf7d3fbed",
    "currency": "USD",
    "paymentMethodDetails": {
      "lockboxPayment": {
        "routingNumber": "001234567",
        "lockboxNumber": "1234567",
        "lockboxPaymentMethodType": "ACH",
        "accountNumber": "0000",
        "authenticationNumber": "000111222"
      }
    },
    ...
    ...
    ...
  }
}

Sample JSON for reversal with Lockbox/Wire:

If the reversalId in the request is a Lockbox/Wire payment type, the following partial response shows the portions that differ for this request.

{
  "reversal": {
    ...
    ...
    ...
    "methodType": "LOCKBOX",
    "paymentId": "b153650f-a293-41f1-988d-1b7cf7d3fbed",
    "currency": "USD",
    "paymentMethodDetails": {
      "lockboxPayment": {
        "routingNumber": "001234567",
        "wireTransferId": "000111222",
        "lockboxNumber": "1234567",
        "lockboxPaymentMethodType": "WIRE",
        "accountNumber": "0000"
      }
    },
    ...
    ...
    ...
  }
}

Sample JSON for reversal with UKDD payment:

If the reversalId in the request is a UKDD payment type, the following partial response shows the portions that differ for this request.

{
  "reversal": {
    ...
    ...
    ...
    "methodType": "UKDD",
    "paymentId": "b153650f-a293-41f1-988d-1b7cf7d3fbed",
    "currency": "GBP",
    "paymentMethodDetails": {
      "ukDirectDebit": {
        "bankSortCode": "0123131",
        "bankAccountNumber": "XXXXX0000",
        "accountHolderName": "Test Name"
      }
    },
    ...
    ...
    ...
  }
}

Sample JSON for reversal with NLSEPA payment:

If the reversalId in the request is a NLSEPA payment type, the following partial response shows the portions that differ for this request.

{
  "reversal": {
    ...
    ...
    ...
    "methodType": "NLSEPA",
    "paymentId": "b153650f-a293-41f1-988d-1b7cf7d3fbed",
    "currency": "EUR",
    "paymentMethodDetails": {
      "paymentId": "urn:uuid:696c40a0-c3e7-11e2-8b8b-0800200c9a66",
      "nlSEPA": {
        "iban": "XXXXXXXXXXXXXX8615",
        "bic": "ABNANL2A"
      }
    },
    ...
    ...
    ...
  }
}

This table shows the possible response codes for this operation:

Response code	Name	Description
200	OK	The request succeeded.
400	Bad Request	A general error has occurred.
401	Unauthorized	The request has not been applied because it lacks valid authentication credentials for the target resource. The credentials are either expired or invalid.
404	Not Found	The server could not find what was requested.
405	Method Not Allowed	The method received in the request line is known by the origin server but is not supported by the target resource.
406	Not Acceptable	The server cannot produce a response matching the list of acceptable values defined in the request.
415	Unsupported Media Type	This error might result if the wrong media type is used in the cURL request.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.

Users with any of the following roles can access this API:

identity:user-admin
admin
billing:admin
observer
billing:observer