-
Notifications
You must be signed in to change notification settings - Fork 0
FundingSources
FundingSources represent different payment processors and APIs that the user has provided to pay for Subscriptions with.
Because FundingSource providers all have different requirements for authentication, each FundingSource provider has their own resource defined. These resources are all represented in responses under the funding_sources property, under their own property within the funding_sources property. The funding_sources property will be an object, with a property for each FundingSource provider.
FundingSources appear as follows:
{
"stripe": [
{
// See the Stripe resource for the contents of this part
}
]
}
Furthermore, all FundingSources share the same base properties, regardless of the extra properties they require.
{
"id": uint64,
"remote_id": string,
"nickname": string,
"last_used": datetime,
"added": datetime,
"user_id": uint64
}
Mutable properties are properties that can be modified through interactions with the API.
- remote_id: a unique identifier that will identify the FundingSource in the provider's system.
- nickname: an optional string the user can modify to supply a custom name for the funding source.
Immutable properties are properties that are created and modified only by the system; there is no way to modify them through the API.
- id: A unique, immutable identifier for this Subscription.
- last_used: the date and time the FundingSource was last used to send money, expressed as RFC 3339.
- added: the date and time the FundingSource first appeared in the system, expressed as RFC 3339.
- user_id: The ID of the User object this FundingSource belongs to.
The Stripe Resource is found under the stripe property in the funding_sources object.
The Stripe Resource has no properties except those defined in the Global Properties section.
This request requires only authentication if it is run for the authenticating User's FundingSources. If it is run against another User's FundingSources, it requires administrative credentials.
GET /users/{username}/funding_sources
This request sets the Last-Modified header to the highest last_used property of the FundingSources returned.
The Content-Type of this request will be funding_sources/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be funding_sources/json.
This request returns a FundingSources resource, containing a property for each FundingSource provider. Each FundingSource provider property's value is a list of that provider's FundingSource resources.
{
"code": 200,
"msg": "Successfully retrieved funding sources",
"funding_sources": {
"stripe": [
{
// See the Stripe Resource for the contents of this part
}
]
}
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | The username query parameter was not set. |
| 403 | ERROR_ACCESS_DENIED | The authenticating user did not have access to the specified user's funding sources. | |
| 404 | ERROR_NOT_FOUND | user | The specified user did not exist. |
| 500 | ACT_OF_GOD | An unknown error occurred. |
This request requires only authentication if it is run for the authenticating User. If it is run for another User, it requires administrative credentials.
POST /users/{username}/funding_sources
Because this request has a body, the Content-Type and Content-Length headers need to be set.
The request body should be a FundingSource Resource container containing arrays of FundingSources according to the provider. Only the Mutable Properties of each FundingSource will be used; the rest will be ignored.
A sample request body:
{
"funding_sources": {
"stripe": [
{
"remote_id": "cus_1j8Opoq5n6k9UG",
"nickname": "Stripe"
}
]
}
}
This request sets the Last-Modified header to the latest added property of the returned FundingSources.
The Content-Type of this request will be funding_sources/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be funding_sources/json.
This request returns a FundingSources resource, containing a property for each FundingSource provider. Each FundingSource provider property's value is a list of the FundingSource resources that were added for that provider.
{
"code": 200,
"msg": "Successfully created funding sources",
"funding_sources": {
"stripe": [
{
// See the Stripe Resource for the contents of this part
}
]
}
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | The username query parameter was not set. |
| 403 | ERROR_ACCESS_DENIED | The authenticating user did not have access to the specified user's funding sources. | |
| 404 | ERROR_NOT_FOUND | user | The specified user did not exist. |
| 500 | ACT_OF_GOD | An unknown error occurred. |
This request requires only authentication if it is run against a FundingSource owned by the authenticating User. If the request is run against a FundingSource owned by another User, the request requires administrative credentials.
GET /users/{username}/funding_sources/{id}
The Content-Type of this request will be funding_sources/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be funding_sources/json.
This request returns a FundingSources resource, containing a property for each FundingSource provider. Each FundingSource provider property's value is a list of the FundingSource resources that were retrieved for that provider.
{
"code": 200,
"msg": "Successfully retrieved funding sources",
"funding_sources": {
"stripe": [
{
// See the Stripe Resource for the contents of this part
}
]
}
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | The username query parameter was not set. |
| 403 | ERROR_ACCESS_DENIED | The authenticating user did not have access to the specified user's funding sources. | |
| 404 | ERROR_NOT_FOUND | user | The specified user did not exist. |
| 500 | ACT_OF_GOD | An unknown error occurred. |
This request requires only authentication if it is run against a FundingSource owned by the authenticating User. If the request is run against a FundingSource owned by another User, the request requires administrative credentials.
PUT /users/{username}/funding_sources/{id}
Because this request has a body, the Content-Type and Content-Length headers need to be set.
The request body should be a specific provider object, e.g. a Stripe Resource. Only the Mutable Properties of the FundingSource will be used; the rest will be ignored. If more than one resource is provided, an error will be thrown.
A sample request body:
{
"funding_sources": {
"stripe": [
{
"nickname": "Stripe"
}
]
}
}
The Content-Type of this request will be funding_sources/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be funding_sources/json.
This request returns a FundingSources resource, containing a property for each FundingSource provider. Each FundingSource provider property's value is a list of the FundingSource resources that were updated for that provider.
{
"code": 200,
"msg": "Successfully updated funding sources",
"funding_sources": {
"stripe": [
{
// See the Stripe Resource for the contents of this part
}
]
}
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | The username query parameter was not set. |
| 403 | ERROR_ACCESS_DENIED | The authenticating user did not have access to the specified user's funding sources. | |
| 404 | ERROR_NOT_FOUND | user | The specified user did not exist. |
| 500 | ACT_OF_GOD | An unknown error occurred. |
This request requires only authentication if it is run against a FundingSource owned by the authenticating User. If the request is run against a FundingSource owned by another User, the request requires administrative credentials.
DELETE /users/{username}/funding_sources/{id}
The Content-Type of this request will be funding_sources/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be funding_sources/json.
This request returns a FundingSources resource, containing a property for each FundingSource provider. Each FundingSource provider property's value is a list of the FundingSource resources that were removed for that provider.
{
"code": 200,
"msg": "Successfully removed funding sources",
"funding_sources": {
"stripe": [
{
// See the Stripe Resource for the contents of this part
}
]
}
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | username | The username query parameter was not set. |
| 403 | ERROR_ACCESS_DENIED | The authenticating user did not have access to the specified user's funding sources. | |
| 404 | ERROR_NOT_FOUND | user | The specified user did not exist. |
| 500 | ACT_OF_GOD | An unknown error occurred. |