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.
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 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.
The main identifier of a payment, like for most other RaiseNow objects, is the
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
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,
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
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|
|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|
|bank_transfer||Bank wire transfers|
|sepa_dd||SEPA Direct Debit|
|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,
Bank transfers can have a field
bank_transfer_type - as of 2022, one of
dd, esr, es, wire.
status_history contains objects reporting a
timestamp (UNIX timestamp in seconds), a coarse
status and a more granular
|The payment has been created but not yet sent to the payment provider|
|The request has been forwarded to the payment provider, we are waiting for an answer|
|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|
|The payment was successful|
|There was a clear error, the payment didn't go through|
|User interaction was needed to proceed, but it didn't come in a timely manner|
|The user explicitly aborted the payment|
|The payment request was technically correct, but the payment provider declined it (e.g. insufficient funds, fraud detection)|
|The payment has been completely refunded|
|The payment has been partially refunded|
|The payment has been reversed|
created holds the creation timestamp, which should be the same as the
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
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_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
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.
If a payment source or a subscription were created together with the payment, fields
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_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
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.
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.
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.
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