-
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,
"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.
- 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.
- 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.
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.
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.
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.
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
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
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}
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}