Follow

Payments API call

You can use the Payments API call to retrieve information for a particular payment, or for multiple payments, filtered by date, contact, or event. You can also create, edit, or delete a payment, allowing you to migrate existing payment records to your Wild Apricot database.

Wild Apricot's API is intended for use by developers with technical expertise. If you need assistance, we provide support via email or through our Developers forum.

Retrieving information for a specific payment

Syntax
GET [baseAPIaddress]/v2/Accounts/[accountID]/Payments/[paymentID]
Example
GET https://api.wildapricot.org/v2/Accounts/58293/Payments/49492

Retrieving multiple payments

You can use the Payments API call to retrieve multiple payments. You must include filter criteria to narrow the results. For details, see Filtering the results (below).

The payments IDs will be listed by document date in descending order.

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Payments/?[filterCriteria]
Example:
GET https://api.wildapricot.org/v2/Accounts/58293/Payments?contactId=725191&StartDate=2016-11-20  

Parameters

The following parameters are used within the Payments API call:

baseAPIaddress
The base address of the API. For more information, see API access options.

version
The version number of the API. Versions 2 and 2.1 are supported for this call. To retrieve a list of API versions, use the Base API call.

accountID
The account identifier that is returned by the Accounts API call.

paymentID
The unique identifier for a payment. Invoices IDs are returned by the Payments API call.

filterCriteria
The criteria used to filter the search results. This is a required parameter. For details, see Filtering the results (below).

Each API call must include an authentication information that verifies your account and prevents others from accessing your data. For more information, see API access options.

Filtering the results

When retrieving information for multiple payments, you must include filter criteria. You can filter the results by specifying a contact or event, by specifying a start and/or end date, and by specifying a set of payment ids. You can combine multiple filter criteria to further narrow the results.

Specifying a contact or event

You can filter the payments by specifying a particular contact and/or event.

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Payments/?contactId=[contactID]&eventId=[eventID]
Example:
GET https://api.wildapricot.org/v2/Accounts/58293/Payments?contactId=725191&eventId=11769

Specifying a start or end document date

You can filter the payments by specifying a start date and/or an end date (using the DocumentDate field).

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Payments/?StartDate=[date]&EndDate=[date]

where date is the start or end date of the range (using the yyyy-mm-dd date format).

Example:
GET https://api.wildapricot.org/v2/Accounts/58293/Payments/?StartDate=2016-11-01&EndDate=2016-11-30

Specifying a set of payment IDs

You can filter the payments by specifying a set of payment IDs.

Syntax
GET [baseAPIaddress]/[version]/Accounts/[accountID]/Payments/?ids=[id1],[id2],[id3]...

where id is the unique identifier of a payment.

Example:
GET https://api.wildapricot.org/v2/Accounts/58293/Payments/?ids=25291894,25291888

Retrieving just payment IDs

You can retrieve just the payment IDs that match the filter criteria by including the idsOnly parameter. This parameter is only available when you specify v2.1 as the API version. The payment IDs will be listed by document date in descending order.

Example
GET https://api.wildapricot.org/v2/Accounts/58293/Payments?eventId=11769&idsOnly=true

Paging

Using the $skip and $top parameters, you can retrieve records in sets or pages. You use the $top parameter to specify the maximum number of records to be returned, and the $skip parameter to specify the number of records to skip. The $skip parameter is incremented each call to return the next set or page of records.

Example

You want to retrieve 50 records using an application that can only process 20 records at a time. Using the following calls, the application retrieves the first set of 20 records, then a second set of 20, and finally, the remaining 10 records.

https://api.wildapricot.org/v2/Accounts/58293/Payments?eventId=11769&$skip=0&$top=20
https://api.wildapricot.org/v2/Accounts/58293/Payments?eventId=11769&$skip=20&$top=20
https://api.wildapricot.org/v2/Accounts/58293/Payments?eventId=11769&$skip=40&$top=20

In this example, the $top specifies the maximum number of records to retrieve (20), and the $skip parameter is incremented from 0 to 20 to 40 to skip the recordsretrieved by the previous call(s).

Response fields

The Payments API call retrieves the following information for each payment.

AllocatedValue
The portion of the payment that is allocated to invoices.

Comment
Any internal notes entered for the payment.

Contact
The contact who made the payment.

CreatedBy
The contact who created the payment (if manually created).

CreatedDate
The date the payment was created.

DocumentDate
The date and time the payment was made.

ID
The unique identifier of the payment.

PaymentType
The type of payment. Possible values: InvoicePayment, DonationPayment. When creating a new payment through the API, the payment type is always InvoicePayment.

PublicComment
Any comments entered for the payer.

Tender
The method used to make the payment.

UpdatedBy
The contact who updated the payment.

UpdatedDate
The date the payment was last updated.

URL
The address of the URL call for the payment.

Value
The amount of the payment.

Sample JSON response

{
"Tender": {
"Id": 1196717,
"Url": "https://api.wildapricot.org/v2.1/accounts/203011/Tenders/1196717",
"Name": "Cash"
},
"Comment": "Paid to admin",
"PublicComment": "Thank you for your support!",
"AllocatedValue": 10,
"Type": "InvoicePayment",
"Value": 10,
"DocumentDate": "2016-11-21T11:14:14-05:00",
"Contact": {
"Id": 29977001,
"Url": "https://api.wildapricot.org/v2.1/accounts/203011/Contacts/29977001"
},
"CreatedDate": "2016-11-21T11:14:14",
"CreatedBy": {
"Id": 29976949,
"Url": "https://api.wildapricot.org/v2.1/accounts/203011/Contacts/29976949"
},
"UpdatedDate": "2016-11-21T11:15:41",
"UpdatedBy": {
"Id": 29976949,
"Url": "https://api.wildapricot.org/v2.1/accounts/203011/Contacts/29976949"
},
"Id": 25291888,
"Url": "https://api.wildapricot.org/v2.1/accounts/203011/Payments/25291888"
}

Sample XML response

<Payment xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://api.wildapricot.org">
<Id>25291888</Id>
<Url>https://api.wildapricot.org/v2.1/accounts/203011/Payments/25291888</Url>
<Contact>
<Id>29977001</Id>
<Url>https://api.wildapricot.org/v2.1/accounts/203011/Contacts/29977001</Url>
</Contact>
<CreatedBy>
<Id>29976949</Id>
<Url>https://api.wildapricot.org/v2.1/accounts/203011/Contacts/29976949</Url>
</CreatedBy>
<CreatedDate>2016-11-21T11:14:14</CreatedDate>
<DocumentDate xmlns:d2p1="http://schemas.datacontract.org/2004/07/System">
<d2p1:DateTime>2016-11-21T16:14:14Z</d2p1:DateTime>
<d2p1:OffsetMinutes>-300</d2p1:OffsetMinutes>
</DocumentDate>
<UpdatedBy>
<Id>29976949</Id>
<Url>https://api.wildapricot.org/v2.1/accounts/203011/Contacts/29976949</Url>
</UpdatedBy>
<UpdatedDate>2016-11-21T11:15:41</UpdatedDate>
<Value>10.0000</Value>
<AllocatedValue>10.0000</AllocatedValue>
<Comment>Paid to admin</Comment>
<PublicComment>Thank you for your support!</PublicComment>
<Tender>
<Id>1196717</Id>
<Url>https://api.wildapricot.org/v2.1/accounts/203011/Tenders/1196717</Url>
<Name>Cash</Name>
</Tender>
<Type>InvoicePayment</Type>
</Payment>

Creating a new payment

You can use a Payments API call to create a payment.

Syntax
POST [baseAPIaddress]/v2/Accounts/[accountID]/Payments
{
"Value": [value],
"Contact":{
"Id": [contactID]
},
"Tender":{
"Id": [tenderID]
},
"paymentField": paymentFieldValue,
"paymentField": paymentFieldValue,
...
}

where Value and Contact are required fields, and additional instances of paymentField can be Tender, Invoices, Comment, or PublicComment. Value must be greater than zero, and will be rounded to 2 decimal places. If, when specifying multiple invoices, the payment value is not enough to cover all specified invoices, the sum will be allocated to invoices in the order in which are specified. When creating a new payment, the payment Type is always InvoicePayment. The payment date will be automatically set to the current date.

Example: payment for specific invoice
POST https://api.wildapricot.org/v2/Accounts/58293/Payments/
{
"Value": 100,
"Contact":{
"Id": 1234567
},
"Invoices":[
{
"Id":12345
}
],
"Tender":{
"Id": 23456
},
"Comment": "Late payment"
}
Example: payment without specifying an invoice
POST https://api.wildapricot.org/v2/Accounts/58293/Payments/
{
"Value": 100,
"Contact":{
"Id": 1234567
},
"Tender":{
"Id": 23456
},
"Comment": "Late payment"
}

If any of the required fields are missing, or if any of the fields include invalid data, a 400 Bad Request error will be returned. For more information, see API status codes.

Modifying a payment

You can update an existing payment using a Payments API call.

Syntax
PUT [baseAPIaddress]/[version]/Accounts/[accountID]/Payments/[paymentID]
{
"Id": paymentID,
"[paymentField]": [paymentFieldValue],
"[paymentField]": [paymentFieldValue],
...
}

where paymentField is a field returned by the Payments API call.

The payment ID must be specified both as a field and within the requesting URL. All other fields are optional.
Example
PUT https://api.wildapricot.org/v2/Accounts/58293/Payments/49492
{
"Id": 49492,
"Value": 100,
"Comment": "Adjusted payment amount",
"UpdatedBy": {
"Id": 29976949
}
}

If successful, the call returns an HTTP status code 200 without any data in the response body.

Deleting a payment

Syntax
DELETE [baseAPIaddress]/v2/Accounts/[accountID]/Payments/[paymentID]
Example
DELETE https://api.wildapricot.org/v2/Accounts/58293/Payments/49492

0 Comments

Please sign in to leave a comment.

Search: WildApricot.com 

About results ( seconds) Sort by: 
Sorry, an error occured when performing search.