Creating a payment instrument

Once you have a created company and added a user to the company, you can create a payment instrument for that user. To do so, you will need the unique company identifier returned in the create company response and the unique user identifier returned in the create user response. The unique identifier for your new payment instrument will be returned in the response (shown in the example below). This identifier will be used in calls to create subscriptions, as well as for managing subscriptions.

If no payment instrument exists yet for the user and company pair, a payment instrument will be created and set to be the default. If a payment instrument does exist, but has a different payment method and is set to be the default, a payment instrument will be created and set to the is_default setting passed in the request. If no is_default setting is provided in the request, the value will be set to 'N', indicating it is not the default payment instrument.

If the payment instrument exists for the given user and company pair, regardless of whether or not it is set to be the default, you will receive a 409 Conflict response, indicating the payment instrument already exists.

URL endpoint: /billing/v1/companies/{companyId}/users/{userId}/paymentInstruments

Method: POST

Parameters:

• companyId - The unique identifier for the company provided by the channel. This id can be obtained either from the response returned when the company is created via the API, or by using the API to list the companies in order to view the id for your company.
• userId - The unique identifier for the user provided by the channel. This id can be obtained either from the response returned when the user is created via the API, or by using the API to list the users for the company in order to view the id for the user.
• A valid JSON or XML object with payment instrument data

HTTP status codes

HTTP Status Code	Description
201 Created	The payment instrument was created.
400 Bad Request	Some required fields were not received.
404 Not Found	The specified company or user was not found.
409 Conflict	The specified payment instrument already exists for the specified company and user.

Below is an example of the most basic payment instrument creation request and response. Additional examples are provided in the example section of this document.

Request

• JSON

POST https://appdirect.com/api/billing/v1/companies/d7a773af-e216-4127-969d-eaf99d5d9cd2/users/f86e98b7-7749-4b26-adef-bc1a2ced873f/paymentInstruments
Host: www.appdirect.com
Authorization	OAuth oauth_version="1.0", oauth_signature_method="HMAC-SHA1", oauth_nonce="VeJO1tP7RKUE1rz", oauth_timestamp="1438728054", oauth_consumer_key="appdirect-91", oauth_signature="xy37tmDbpwuIHZJIioRSB3GGAhM%3D"
Content-Type	application/json
{
    "paymentMethod":"CREDIT_CARD",
    "billingAddress":{
        "firstName":"Demo",
        "lastName":"User",
        "street1":"50 Grove St",
        "city":"Somerville",
        "country":"US",
        "state":"MA",
        "zip":"02114",
        "phone":"4159991100"
    },
    "creditCard":{
        "name":"Demo User",
        "number":"4111111111111111",
        "expirationMonth":"5",
        "expirationYear":"2017",
        "securityCode":111,
        "type":"VISA"
    }
}

• XML

POST https://appdirect.com/api/billing/v1/companies/d7a773af-e216-4127-969d-eaf99d5d9cd2/users/f86e98b7-7749-4b26-adef-bc1a2ced873f/paymentInstruments

Host: www.appdirect.com
Authorization	OAuth oauth_version="1.0", oauth_signature_method="HMAC-SHA1", oauth_nonce="VeJO1tP7RKUE1rz", oauth_timestamp="1438728054", oauth_consumer_key="appdirect-91", oauth_signature="xy37tmDbpwuIHZJIioRSB3GGAhM%3D"
Content-Type	application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<paymentInstrument>
	<paymentMethod>CREDIT_CARD</paymentMethod>
	<billingAddress>
		<firstName>Demo</firstName>
		<lastName>User</lastName>
		<street1>50 Grove St</street1>
		<city>Somerville</city>
		<country>US</country>
		<state>MA</state>
		<zip>02114</zip>
		<phone>4159991100</phone>
	</billingAddress>
	<creditCard>
		<name>Demo User</name>
		<number>4111111111111111</number>
		<expirationMonth>5</expirationMonth>
		<expirationYear>2017</expirationYear>
		<securityCode>111</securityCode>
		<type>VISA</type>
	</creditCard>
</paymentInstrument>

Response

• JSON

Status Code: 201 Created
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 887
Content-Type: application/xml;charset=UTF-8
Date: Tue, 11 Aug 2015 15:46:15 GMT
Expires: 0
Location: http://www.appdirect.com/api/billing/v1/paymentInstruments/2d54fbc8-6c35-4438-ad8e-d9c9768aaa6a
Pragma: no-cache
Server: Apache-Coyote/1.1
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
x-content-type-options: nosniff
{
    "id": "2d54fbc8-6c35-4438-ad8e-d9c9768aaa6a",
    "company": {
      "-id": "2e983f07-99d1-46cd-920a-dd0c8de5bc48",
      "-href": "http://www.appdirect.com/api/account/v1//companies/2e983f07-99d1-46cd-920a-dd0c8de5bc48"
    },
    "user": {
      "-id": "5019a0a6-a1e3-4d6a-85d3-6b6993afe96d",
      "-href": "http://www.appdirect.com/api/account/v1//users/5019a0a6-a1e3-4d6a-85d3-6b6993afe96d"
    },
    "paymentMethod": "CREDIT_CARD",
    "billingAddress": {
      "city": "Somerville",
      "country": "US",
      "state": "MA",
      "street1": "50 Grove St",
      "zip": "02114",
      "firstName": "Demo",
      "lastName": "User",
      "phone": "4159991100"
    },
    "creditCard": {
      "expirationMonth": "5",
      "expirationYear": "2017",
      "type": "VISA"
    },
    "createdOn": "2015-08-11T09:46:15.628-06:00",
    "isDefault": "false"
}

-XML

Status Code: 201 Created
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Length: 887
Content-Type: application/xml;charset=UTF-8
Date: Tue, 11 Aug 2015 15:46:15 GMT
Expires: 0
Location: http://www.appdirect.com/api/billing/v1/paymentInstruments/2d54fbc8-6c35-4438-ad8e-d9c9768aaa6a
Pragma: no-cache
Server: Apache-Coyote/1.1
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
x-content-type-options: nosniff
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<paymentInstrument>
  <id>2d54fbc8-6c35-4438-ad8e-d9c9768aaa6a</id>
  <company id="2e983f07-99d1-46cd-920a-dd0c8de5bc48" href="http://www.appdirect.com/api/account/v1//companies/2e983f07-99d1-46cd-920a-dd0c8de5bc48"/>
  <user id="5019a0a6-a1e3-4d6a-85d3-6b6993afe96d" href="http://www.appdirect.com/api/account/v1//users/5019a0a6-a1e3-4d6a-85d3-6b6993afe96d"/>
  <paymentMethod>CREDIT_CARD</paymentMethod>
  <billingAddress>
    <city>Somerville</city>
    <country>US</country>
    <state>MA</state>
    <street1>50 Grove St</street1>
    <zip>02114</zip>
    <firstName>Demo</firstName>
    <lastName>User</lastName>
    <phone>4159991100</phone>
  </billingAddress>
  <creditCard>
    <expirationMonth>5</expirationMonth>
    <expirationYear>2017</expirationYear>
    <type>VISA</type>
  </creditCard>
  <createdOn>2015-08-11T09:46:15.628-06:00</createdOn>
  <isDefault>false</isDefault>
  <parameters/>
</paymentInstrument>