Payments
What is a Payment?
A payment represents an attempted or succeeded transfer of money (for a donation, a purchase, a subscription fee...) from a payer to an organisation's account.
One-off payments can be created through the payments API, usually using a payment widget, or by charging an existing payment source. Recurring payments are initiated by a subscription by charging automatically a payment source. The structure of a payment object is very similar in both cases.
Payment information
Payments are rather complex objects. They contain some core information (like date, amount and currency, status, the payment method that was used), a supporter snapshot if provided, custom parameters, possibly references to the payment source and subscription that were charged or that were created together with the payment, besides technical data from the payment provider.
Amount
amount holds the paid amount in minor units - basically, in cents or thousandths for currencies supporting them, in units otherwise. It is responsibility of the client to know what are the minor units of each currency.
currency_identifier contains the currency ISO 4217, in capital letters.
Identifiers
The main identifier of a payment, like for most other RaiseNow objects, is the uuid.
Payment providers usually assign an id to every payment, and return it in the payment response: This is stored as provider_payment_id. It's available only after the payment request has been sent to the provider, and may be missing if the payment failed for technical reasons. It can usually be used to look up a payment in the provider dashboard or API.
Some providers must receive an identifier and may not support uuids. In this case, RaiseNow generates the external_payment_id.
For advanced integrations, key-value pairs are stored in the object additional_identifiers. These are handled by RaiseNow and cannot be specified by the customer.
Payment method-related fields
method_profile_uuid specifies the method profile used in the payment request or attached to the payment source, and provider_profile_uuid the provider profile to which it belongs. Similarly, account_uuid and organisation_uuid indicate the account and organisation of the provider profile. test_mode is a boolean reporting whether the method profile is in test mode or production - in normal cases, it should always be false.
payment_provider and payment_method contain the identifiers of the payment provider and method that were used to make the payment.
Payment providers as of 2022:
| Payment provider code | Name |
|---|---|
| stripe | Stripe |
| twint | TWINT (Switzerland only) |
| raisenow_reconciliation | RaiseNow direct integrations with banking systems |
Payment methods as of 2022:
| Payment method code | Name |
|---|---|
| twint | TWINT (Switzerland only) |
| card | Credit or debit card |
| sms | SMS |
| bank_transfer | Bank wire transfers |
| ch_dd | DirectDebit (Switzerland) |
| ch_ta | LSV (Switzerland) |
| ideal | iDEAL (Netherlands) |
| sepa_dd | SEPA Direct Debit |
| bancontact | Bancontact (Belgium) |
| sofort | Sofort |
| eps | EPS |
| wallet | Wallets (Google Pay, Apple Pay) |
Credit or debit card payments can have a field brand_code with the card brand (e.g. Visa, Mastercard, etc.). The codes may change depending on payment provider and flow.
Wallet payments can have a field wallet_type - as of 2022, google_pay or apple_pay.
Bank transfers can have a field bank_transfer_type - as of 2022, one of dd, esr, es, wire.
Status history
The array status_history contains objects reporting a timestamp (UNIX timestamp in seconds), a coarse status and a more granular reason.
| Status | Reason | Description |
|---|---|---|
pending | new | The payment has been created but not yet sent to the payment provider |
pending | The request has been forwarded to the payment provider, we are waiting for an answer | |
unknown | The request has been forwarded to the payment provider but there's been an unexpected error, we don't know if the payment succeeded or not | |
succeeded | succeeded | The payment was successful |
failed | error | There was a clear error, the payment didn't go through |
user_timeout | User interaction was needed to proceed, but it didn't come in a timely manner | |
user_aborted | The user explicitly aborted the payment | |
declined | The payment request was technically correct, but the payment provider declined it (e.g. insufficient funds, fraud detection) | |
refunded | refunded | The payment has been completely refunded |
partially_refunded | partially_refunded | The payment has been partially refunded |
reversed | reversed | The payment has been reversed |
Field created holds the creation timestamp, which should be the same as the new entry.
Fields last_status, last_status_reason and last_status_timestamp can be used to see more conveniently the most current status.
Refunds and reversals
Refunds and reversals, if any, are saved in objects refunds and reversals. It is possible to have multiple refunds, for instance if some of them failed, or in case of partial reversals. The total sum of successful refunds cannot exceed the payment's original amount. There should never be more than one reversal per payment - however, due to the way they are imported such a case cannot be excluded. If there are refunds or reversals, flags has_refunds and has_reversals are set to true, to simplify search and consumption.
Each refund exposes fields uuid, created, amount, last_status, last_status_reason, last_status_timestamp. Their meaning is the same as for payments.
Reversals have the same fields, plus currency and method_profile_uuid, needed because a reversal may be imported from external sources without a matching payment. Reversals are created during the reconciliation process based on information from banks, enabled only upon request and for specific setups.
Related entities
If a payment source or a subscription were created together with the payment, fields created_payment_source_uuid and created_subscription_uuid will be filled. On the dual case, if the payment was created by charging a payment source or subscription they will be reported in charged_payment_source_uuid and charged_subscription_uuid, invoice_uuid, charge_attempt_uuid. Field charged_by indicates whether the charge was triggered through RaiseNow or a payment provider.
If the payment is linked to a stored supporter, its UUID is saved as supporter_uuid. A copy of the supporter's data at the time of the payment is saved as a supporter snapshot in the object supporter_snapshot. If the payment was done charging an existing subscription or payment source, the current supporter's data is also copied into the supporter snapshot.
Custom and RaiseNow parameters
Object custom_parameters holds key-value pairs that can be freely set by the customer. Values are limited to strings. They can be set when the payment is made or changed with the replace or patch custom parameters endpoints.
Object raisenow_parameters holds an arbitrary structure used by RaiseNow for internal purposes.
Custom parameters for payments done through the payments API are taken from the request. For payment source charges, they are taken first from the payment source's custom parameters, and can be overridden in the request. For subscription charges, they are taken first from the subscription's custom parameters, then from the payment source's.
Other data
Pricing data is saved in the pricing object. This will report only the fees RaiseNow computes directly. For instance, Stripe fees would not be included, as they are computed and applied by Stripe.
Array metadata contains technical information about the parameters used to make the payment, responses from the payment provider, etc. It holds a sequence of objects with a compound key formed by type, group, name, a string value and a created timestamp.