-
Notifications
You must be signed in to change notification settings - Fork 0
Payments
Payments represent individual payments and donations that users have made.
The Payment Resource is represented in responses under the payments property. The payments property will be an array of Payments.
Payments appear as follows:
{
"id": uint64,
"remote_id": string,
"amount": int,
"message": string,
"created": datetime,
"completed": datetime,
"user_id": uint64,
"funding_source_id": uint64,
"funding_source_provider": string,
"anonymous": bool,
"campaign": uint64,
"status": string,
"error": string
}
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.
- amount: the amount of money (in US cents—e.g. 100 = $1.00) that is being paid.
- message: an optional, user-specified message to accompany the Payment.
- user_id: the ID of the user who is making the payment.
- funding_source_id: the ID of the funding source that the payment is being made from.
-
funding_source_provider: the provider associated with the funding source specified by
funding_source_id. See the Funding Source resource for more information. - anonymous: whether the payment should be publicly attributed to the user.
- campaign: the ID of the campaign the payment is being made to.
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 Payment.
- created: the date and time the Payment was made, expressed as RFC 3339.
- completed: the date and time the Payment was completed (successfully or unsuccessfully), expressed as RFC 3339.
-
status: a string representing the status of the Payment. Valid strings are:
- pending: the Payment has not been charged yet.
- charging: the Payment is in the process of being charged.
- refunding: the Payment is in the process of being refunded.
- refunded: the Payment has been refunded to the user.
- succeeded: the Payment has successfully been charged.
- error: there was an error processing the Payment.
- retry: the user has indicated the payment should be retried.
- error: a string representing the error the payment encountered. These are dependent on the Funding Source used for the Payment and can be found in the Errors section of the Charge method below.
This request does not require authentication. If the request is not authenticated, only payments with a status of "succeeded" or "pending" will be returned, and they will only contain the id, created, completed, amount, message, and campaign fields. Payments that have anonymous set to True will not return a user ID.
If this request is authenticated, the full information for Payments made by the authenticating user will be returned. Payments made by other users will have the above restrictions applied.
If this request is made with administrative credentials, it will return all fields for all Payments, no matter what the values of their fields.
GET /payments
The following URL parameters are accepted when listing Payments, and will filter the list accordingly:
- after: the ID of a Payment. Only Payments after that Payment will be returned.
- before: the ID of a Payment. Only Payments after that Payment will be returned.
- count: the maximum number of Payments to return, as an integer. Defaults to 20, with a maximum of 100.
- status: a valid status string. Only Payments that match that status will be returned.
This request sets the Last-Modified header to the last completed or created property of the Payments returned, whichever is greater.
The Content-Type of this request will be payments/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be payments/json.
This request returns a list of Payment resources as a JSON array:
{
"code": 200,
"msg": "Successfully retrieved a list of payments",
"payments": [
{
// See the Payment Resource for the contents of this part
},
{
// Set the Payment Resource for the contents of this part
}
]
}
In the event no payments are to be returned, an empty array will be returned.
| Status | Code | Field | Explanation |
|---|---|---|---|
| 403 | ERROR_ACCESS_DENIED | status | The authorising user does not have access to the status specified. |
| 400 | ERROR_INVALID_FORMAT | after | The specified after parameter is not a valid ID. |
| 400 | ERROR_INVALID_FORMAT | before | The specified before parameter is not a valid ID. |
| 400 | ERROR_INVALID_FORMAT | count | The specified count parameter is not a valid integer. |
| 400 | ERROR_INVALID_VALUE | count | The specified count parameter must be positive. |
| 400 | ERROR_TOO_LONG | count | The specified count parameter is too high. |
| 500 | ERROR_ACT_OF_GOD | Unknown error occurred. |
This request does not require authentication. If the request is not authenticated, only payments with a status of "succeeded" or "pending" will be returned, and they will only contain the id, created, completed, amount, message, and campaign fields. Payments that have anonymous set to True will not return a user ID.
If this request is authenticated, the full information for Payments made by the authenticating user will be returned. Payments made by other users will have the above restrictions applied.
If this request is made with administrative credentials, it will return all fields for all Payments, no matter what the values of their fields.
GET /campaigns/{id}/payments
The following URL parameters are accepted when listing Payments, and will filter the list accordingly:
- after: the ID of a Payment. Only Payments after that Payment will be returned.
- before: the ID of a Payment. Only Payments after that Payment will be returned.
- count: the maximum number of Payments to return, as an integer. Defaults to 20, with a maximum of 100.
- status: a valid status string. Only Payments that match that status will be returned.
This request sets the Last-Modified header to the last completed or created property of the Payments returned, whichever is greater.
The Content-Type of this request will be payments/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be payments/json.
This request returns a list of Payment resources as a JSON array:
{
"code": 200,
"msg": "Successfully retrieved a list of payments",
"payments": [
{
// See the Payment Resource for the contents of this part
},
{
// Set the Payment Resource for the contents of this part
}
]
}
In the event no payments are to be returned, an empty array will be returned.
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_INVALID_FORMAT | campaign | The campaign ID specified was not a valid ID format. |
| 403 | ERROR_ACCESS_DENIED | status | The authorising user does not have access to the status specified. |
| 400 | ERROR_INVALID_FORMAT | after | The specified after parameter is not a valid ID. |
| 400 | ERROR_INVALID_FORMAT | before | The specified before parameter is not a valid ID. |
| 400 | ERROR_INVALID_FORMAT | count | The specified count parameter is not a valid integer. |
| 400 | ERROR_INVALID_VALUE | count | The specified count parameter must be positive. |
| 400 | ERROR_TOO_LONG | count | The specified count parameter is too high. |
| 500 | ERROR_ACT_OF_GOD | Unknown error occurred. |
This request does not require authentication. If the request is not authenticated, only payments with a status of "succeeded" or "pending" will be returned, and they will only contain the id, created, completed, amount, message, and campaign fields. Payments that have anonymous set to True will not return a user ID.
If this request is authenticated, the full information for Payments made by the authenticating user will be returned. Payments made by other users will have the above restrictions applied.
If this request is made with administrative credentials, it will return all fields for all Payments, no matter what the values of their fields.
GET /users/{username}/payments
The following URL parameters are accepted when listing Payments, and will filter the list accordingly:
- after: the ID of a Payment. Only Payments after that Payment will be returned.
- before: the ID of a Payment. Only Payments after that Payment will be returned.
- count: the maximum number of Payments to return, as an integer. Defaults to 20, with a maximum of 100.
- status: a valid status string. Only Payments that match that status will be returned.
This request sets the Last-Modified header to the last completed or created property of the Payments returned, whichever is greater.
The Content-Type of this request will be payments/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be payments/json.
This request returns a list of Payment resources as a JSON array:
{
"code": 200,
"msg": "Successfully retrieved a list of payments",
"payments": [
{
// See the Payment Resource for the contents of this part
},
{
// Set the Payment Resource for the contents of this part
}
]
}
In the event no payments are to be returned, an empty array will be returned.
| Status | Code | Field | Explanation |
|---|---|---|---|
| 403 | ERROR_ACCESS_DENIED | Authorising user does not have access to the specified user's payments | |
| 404 | ERROR_NOT_FOUND | username | The user associated with the specified username could not be found. |
| 403 | ERROR_ACCESS_DENIED | status | The authorising user does not have access to the status specified. |
| 400 | ERROR_INVALID_FORMAT | after | The specified after parameter is not a valid ID. |
| 400 | ERROR_INVALID_FORMAT | before | The specified before parameter is not a valid ID. |
| 400 | ERROR_INVALID_FORMAT | count | The specified count parameter is not a valid integer. |
| 400 | ERROR_INVALID_VALUE | count | The specified count parameter must be positive. |
| 400 | ERROR_TOO_LONG | count | The specified count parameter is too high. |
| 500 | ERROR_ACT_OF_GOD | Unknown error occurred. |
This request does not require authentication. If the request is not authenticated, only payments with a status of "succeeded" or "pending" will be returned, and they will only contain the id, created, completed, amount, message, and campaign fields. Payments that have anonymous set to True will not return a user ID.
If this request is authenticated, the full information for Payments made by the authenticating user will be returned. Payments made by other users will have the above restrictions applied.
If this request is made with administrative credentials, it will return all fields for all Payments, no matter what the values of their fields.
GET /funding_sources/{id}/payments
The following URL parameters are accepted when listing Payments, and will filter the list accordingly:
- after: the ID of a Payment. Only Payments after that Payment will be returned.
- before: the ID of a Payment. Only Payments after that Payment will be returned.
- count: the maximum number of Payments to return, as an integer. Defaults to 20, with a maximum of 100.
- status: a valid status string. Only Payments that match that status will be returned.
This request sets the Last-Modified header to the last completed or created property of the Payments returned, whichever is greater.
The Content-Type of this request will be payments/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be payments/json.
This request returns a list of Payment resources as a JSON array:
{
"code": 200,
"msg": "Successfully retrieved a list of payments",
"payments": [
{
// See the Payment Resource for the contents of this part
},
{
// Set the Payment Resource for the contents of this part
}
]
}
In the event no payments are to be returned, an empty array will be returned.
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_INVALID_FORMAT | funding_source | The funding source ID specified is not a valid ID format. |
| 403 | ERROR_ACCESS_DENIED | status | The authorising user does not have access to the status specified. |
| 400 | ERROR_INVALID_FORMAT | after | The specified after parameter is not a valid ID. |
| 400 | ERROR_INVALID_FORMAT | before | The specified before parameter is not a valid ID. |
| 400 | ERROR_INVALID_FORMAT | count | The specified count parameter is not a valid integer. |
| 400 | ERROR_INVALID_VALUE | count | The specified count parameter must be positive. |
| 400 | ERROR_TOO_LONG | count | The specified count parameter is too high. |
| 500 | ERROR_ACT_OF_GOD | Unknown error occurred. |
If this request is made without authentication, it will only return the id, amount, message, created, completed, user_id, and campaign fields. Furthermore, it will only display information about Payments whose status is "succeeded" or "pending".
If this request is made by a user with administrative credentials or the user the Payment belongs to, all fields will be returned, and Payments of any status will be returned.
GET /payments/{id}
This request sets the Last-Modified header to the created property of the Payment or the completed property of the Payment, whichever is greater.
The Content-Type of this request will be payments/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be payments/json.
This request returns a list of Payment resources as a JSON array. The array will only have one item:
{
"code": 200,
"msg": "Successfully retrieved payment information",
"payments": [
{
// See the Payment Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | id | No payment ID was specified in the request. |
| 400 | ERROR_INVALID_FORMAT | id | The specified payment ID is not a valid ID format. |
| 404 | ERROR_NOT_FOUND | id | The payment specified was not found. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. |
This request requires only authentication if it is creating a Payment for the authenticating user. If it is creating a Payment for another user, it requires administrative credentials.
POST /payments
The request body should be a JSON array of Payment Resources. Only the Mutable Properties will be used; the rest will be ignored. Additionally, the remoted_id property will be ignored.
A sample request body:
{
"payments": [
{
"amount": 1000,
"message": "My contribution for the year",
"user_id": 12,
"funding_source_id": 18,
"funding_source_provider": "stripe",
"anonymous": false,
"campaign": 3
}
]
}
The request responds with the Payment that was created.
This request sets the Last-Modified header to the created property of the Payment returned.
The Content-Type of this request will be payments/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be payments/json.
This request returns a list of Payment resources as a JSON array. The array will contain the Payment that was created:
{
"code": 201,
"msg": "Successfully created payment",
"payments": [
{
// See the Payment Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_BAD_REQUEST_FORMAT | The request body was not a valid JSON object. | |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_MISSING_PARAM | payment | There was no payment field in the request body. |
| 400 | ERROR_MISSING_PARAM | payment.amount | There was no amount field in the payment object. |
| 400 | ERROR_TOO_SHORT | payment.amount | The payment amount was too low. Use a higher payment amount. |
| 400 | ERROR_MISSING_PARAM | payment.user_id | An invalid User ID was used in the payment object. |
| 403 | ERROR_ACCESS_DENIED | payment.user_id | The authorising user cannot create payments for the specified user. |
| 400 | ERROR_MISSING_PARAM | payment.funding_source_id | An invalid Funding Source ID was used in the payment object. |
| 400 | ERROR_MISSING_PARAM | payment.funding_source_provider | No funding source provider was specified in the payment object. |
| 400 | ERROR_INVALID_VALUE | payment.funding_source_provider | The funding source provider specified is not a valid provider. |
| 400 | ERROR_MISSING_PARAM | payment.campaign | An invalid campaign ID was used in the payment object. |
| 404 | ERROR_NOT_FOUND | payment.funding_source_id | The funding source specified was not found. |
| 400 | ERROR_WRONG_OWNER | payment.funding_source_id | The funding source specified does not belong to the specified user. |
This request requires administrative credentials. It will reply with a 403 error if the authorising user does not have administrative access to the server.
PUT /payments/{id}/status
The request body should be a Payment Resource. Only the status property will be used; the rest will be ignored. If the status property is set to "charging", the Funding Source specified by the funding_source_id property will be charged the amount specified by the amount property. If the status property is set to "refunding", the Funding Source specified by the funding_source_id property will be refunded the amount specified by the amount property.
A sample request body:
{
"payment": {
"status": "charging"
}
}
This request sets the Last-Modified header to the created property of the Payment returned.
The Content-Type of this request will be payments/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be payments/json.
This request returns a list of Payment resources as a JSON array. The array will only have on item—the Payment that was charged:
{
"code": 20,
"msg": "Charging the payment",
"payments": [
{
// See the Payment Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 403 | ERROR_ACCESS_DENIED | The authenticating user does not have access to update payment statuses. | |
| 400 | ERROR_BAD_REQUEST_FORMAT | The request body was not a valid JSON object. | |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_MISSING_PARAM | payment | No payment field was included in the request object. |
| 400 | ERROR_MISSING_PARAM | payment.status | No payment status was included in the payment object. |
| 400 | ERROR_INVALID_VALUE | payment.status | An invalid payment status was included in the payment object. |
| 400 | ERROR_MISSING_PARAM | id | No payment ID was specified. |
| 400 | ERROR_INVALID_FORMAT | id | The payment ID specified is not a valid ID format. |
| 404 | ERROR_NOT_FOUND | id | The payment specified could not be found. |
This request requires only authentication if it is run against a Payment owned by the authenticating user that has not been charged yet. If it is run against a Payment owned by another user or a Payment that has been charged, it requires administrative credentials.
If a Payment that has not been charged is modified, the new information will be used when charging the Payment. If a Payment that has been charged is modified, only the record of the Payment will be modified.
PUT /payments/{id}
The request body should be a Payment Resource. Only the Mutable Properties will be used; the rest will be ignored. Furthermore, the status, remote_id, completed, and user_id will be ignored unless administrative credentials are used when authenticating credentials.
A sample request body:
{
"payment": {
"amount": 2000,
"message": "Double or nothing",
"anonymous": true
}
}
This request sets the Last-Modified header to the created property of the Payment returned, or (if it is set) the completed property of the Payment returned.
The Content-Type of this request will be payments/encoding. for example, when returned in a JSON encoding (the only option available in version 1), the Content-Type will be payments/json.
This request returns a list of Payment resources as a JSON array. The array will only have one item—the Payment that was modified:
{
"code": 200,
"msg": "Successfully updated the Payment",
"payments": [
{
// See the Payment Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_BAD_REQUEST_FORMAT | ||
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 400 | ERROR_MISSING_PARAM | payment | No payment field was supplied in the request object. |
| 400 | ERROR_TOO_SHORT | payment.amount | The specified payment amount was too small. |
| 403 | ERROR_ACCESS_DENIED | payment.user_id | The authenticating user does not have access to the specified user's payments. |
| 400 | ERROR_MISSING_PARAM | id | No payment ID was specified. |
| 400 | ERROR_INVALID_FORMAT | id | The payment ID specified was not a valid ID. |
| 404 | ERROR_NOT_FOUND | id | The payment specified could not be found. |
| 400 | ERROR_MISSING_PARAM | payment.funding_source_provider | A funding source ID was specified, but no funding source provider was specified. |
| 400 | ERROR_MISSING_PARAM | payment.funding_source_id | A funding source provider was specified, but no funding source ID was specified. |
| 400 | ERROR_INVALID_VALUE | payment.funding_source_provider | The funding source provider specified is not a valid funding source provider. |
| 404 | ERROR_NOT_FOUND | payment.funding_source_id | The funding source specified was not found. |
| 400 | ERROR_WRONG_OWNER | payment.funding_source_id | The funding source specified does not belong to the user that owns the payment. |
| 403 | ERROR_ACCESS_DENIED | payment.status | The authenticating user does not have access to updating non-pending payments. |
This request requires only authentication if it is run against a Payment owned by the authenticating user that has not been charged yet. If it is run against a Payment owned by another user or a Payment that has been charged, it requires administrative credentials.
If a Payment that has not been charged is deleted, the Funding Source will not be charged. If a Payment that has been charged is deleted, only the record of the Payment will be deleted.
DELETE /payments/{id}
This request sets the Last-Modified header to the created property of the Payment returned or (if it is set) the completed property of the Payment returned.
The **Content-Type of this request will be payments/encoding. For example, when returned in JSON encoding (the only option available in version 1), the Content-Type will be payments/json.
This request returns a list of Payment resources as a JSON array. The array will only have one item—the Payment that was just deleted:
{
"code": 200,
"msg": "Successfully deleted the payment",
"payments": [
{
// See the Payment Resource for the contents of this part
}
]
}
| Status | Code | Field | Explanation |
|---|---|---|---|
| 400 | ERROR_MISSING_PARAM | id | No payment ID was specified. |
| 400 | ERROR_INVALID_FORMAT | id | The payment ID specified was not a valid ID. |
| 404 | ERROR_NOT_FOUND | id | The payment specified was not found. |
| 500 | ERROR_ACT_OF_GOD | An unknown error occurred. | |
| 403 | ERROR_ACCESS_DENIED | payment.user_id | The authenticating user did not have access to the specified user's payments. |
| 403 | ERROR_ACCESS_DENIED | payment.status | The authenticating user does not have access to delete non-pending payments. |