Integrating Payment APIs

info

Before integrating, make sure you have familiarised yourself with Authentication mechanisms.

The Initialise Payment endpoint offers a generic way of performing payments with any payment method.

Depending on the payment provider and method, the process will require different input fields. For instance, a payment with credit cards usually needs cardholder name, card number, expiry date and CVV; by contrast, a SEPA Direct Debit payment requires IBAN and bank account owner name.

The steps needed to perform a payment can also vary: For card payments, in countries subject to the SCA (Strong Customer Authentication) regulations, additional steps to fulfill 3d-secure verification can be required. For SEPA Direct Debit no further steps are necessary.

In order to fulfill these varied requirements, the flow is built in a dynamic, guided way. It follows these base steps:

1. The client sends a POST request to the /payments endpoint
2. The server creates a payment and initialises it
3. The client receives a response containing a payment UUID (unique identifier), its status and possibly an action field (e.g. redirect to a third-party website) - other data may be present as well and will be presented later
4. If action is none, the flow is concluded. The payment is in the status that has been reported. Asynchronous flows (e.g. Sofort) may require configuring webhooks to get further updates.
5. If an action is specified, the client must perform it. The types of actions will be detailed later.

Basic request

The basic payment request is structured as follows:

{
  "account_uuid": <string>,
  "profile": <string>,
  "test_mode": <boolean>,
  "amount": {
    "value": <integer>,
    "currency": <string>
  },
  "return_url": <string>,
  "payment_information": {
    // Depending on provider and method
  }
}

• account_uuid: UUID of the account to which the payment will belong
• profile: UUID of the payment method profile to use; must belong to the account
• test_mode: This must match the test mode value of the profile
• amount: Integer value in minor units (usually cents) and currency in ISO-4217 format
• return_url: If the user is sent to a third-party website, they will be redirected to this url afterwards
• payment_information: Specific data for the payment method and provider, e.g. credit card details

The response is structured like:

{
  "objects": {
    "payment_uuid": <string>,
    "payment_status": <string>,
    "reason": <string>
  },
  "action": {
    "action_type": <string>,
    // Other parameters depending on the acion type
  }
}

• payment_uuid: unique identifier of the payment
• payment_status: high-level status of the payment
• reason: detail about the status of the payment

Response actions and redirect flows

No action

If action.action_type is none, the flow is complete and nothing more must be done.

If objects.payment_status is succeeded or failed, the process can be considered concluded. If it's pending and the payment flow is asynchronous, the process will continue in the background; server-side updates should be received via webhooks.

Redirect flows

If action.action_type is redirect, the donor must be redirected to the url specified in action.url. This is a common case for credit card payments in case of 3d-secure flow, and for methods requiring the donor to log in or authorise a payment on a third-party website (e.g. PayPal or their e-banking platform).

In most cases, after these steps the donor will be sent back to RaiseNow. RaiseNow will then finalise the payment, if needed, and automatically redirect the donor to the return_url from the initial payment request. The payment UUID and status will be appended as query string parameters: However, since they can be forged, they should only be used for non-critical purposes (e.g. showing a Thank you page). In order to receive a trusted and reliable payment confirmation, using webhooks is strongly recommended.

Payment status

The response contains a generic payment status and a more detailed reason. The following table summarises them.

status	reason	description
pending	new	Payment request received, the payment provider has not been contacted yet. This is a transient reason.
pending	pending	The payment has been initialised at the payment provider.
pending	unknown	Something unexpected happened, the payment status is unknown. Automatic attempts will be made to correct it.
succeeded	succeeded	Payment succeeded.
failed	error	Payment failed due to a generic error.
failed	user_timeout	The user didn't complete the payment in time.
failed	aborted_by_user	The user explicitly cancelled the payment process.
failed	declined	The payment instrument was declined by the payment provider.
refunded	refunded	The payment has been completely refunded.
partially_refunded	partially_refunded	The payment has been partially refunded.

Adding payment sources and subscriptions

Some payment methods allow for storing the instrument details securely in a payment source. To do it, it is sufficient to set the flag create_payment_source to true. It will be possible to charge the payment source without supporter intervention through the Charge PaymentSource API endpoint.

Additionally, it is possible to set up a subscription. This will create a payment source behind the scenes, and charge it automatically at the requested interval. The request can specify any subscription parameter in the subscription field:

{
  "account_uuid": <string>,
  "profile": <string>,
  "test_mode": <boolean>,
  "amount": {
    "value": <integer>,
    "currency": <string>
  },
  "return_url": <string>,
  "payment_information": {
    // Depending on provider and method
  },
  "subscription": {
    "timezone": "Europe/Berlin",
    "recurring_interval": "1 * *"
  }
}

If a subscription or payment source are created, the response will contain their details:

{
  "objects": {
    "payment_uuid": <string>,
    "payment_status": <string>,
    "payment_source_uuid": <string>,
    "payment_source_status": <string>,
    "reason": <string>,
    "subscription_uuid": <string>
  },
  "action": {
    "action_type": <string>,
    // Other parameters depending on the acion type
  }
}

It is still necessary to complete the payment in order to activate the payment source and subscription.

Attaching custom and supporter data

It is possible to attach both custom parameters and supporter data to a payment.

In the base case, supporter data is stored as a supporter snapshot; a fully fledged supporter object will be created if either flag create_supporter or create_payment_source is set to true, or if a subscription is created simultaneously.

In the following example, supporter data is stored as a snapshot only:

{
  "account_uuid": <string>,
  "profile": <string>,
  "test_mode": <boolean>,
  "amount": {
    "value": <integer>,
    "currency": <string>
  },
  "return_url": <string>,
  "payment_information": {
    // Depending on provider and method
  },
  "custom_parameters": {
    "comment": "Thank you for your efforts!",
    "referral_source": "friends"
  },
  "supporter": {
    "first_name": "Jane",
    "last_name": "Doe",
    "city": "Springfield"
  }
}

Stripe payments

This section provides further information for performing payments with Stripe payment methods. Depending on your country and Stripe account settings, not all methods may be available.

Credit card

The section payment_information must contain:

{
  "number": <string>,
  "expiry_month": <integer MM>,
  "expiry_year": <integer YYYY>,
  "cvv": <integer>
}

A complete example card payment is:

{
  "account_uuid": "fb5683e4-5629-4626-9d76-b81139bc673c",
  "profile": "09bed958-0eab-4c42-b026-ee34cdad02a9",
  "test_mode": true,
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "payment_information": {
      "number": "4111111111111111",
      "expiry_month": "10",
      "expiry_year": "2030",
      "cvv": "737"
    },
  "return_url": "https://futurogoal.raisenow.com/payments"
}

Remember that amount.value is represented in minor units, so 1000 means 10.00 EUR, as the minor units for Euro are cents.

If no 3D-Secure flow is needed, the response will be like:

{
  "action": {
    "action_type": "none"
  }, 
  "objects": {
    "payment_uuid": "48cc3893-73fb-4466-80ea-4c89fe998843",
    "payment_status": "succeeded",
    "reason": "active"
  }
}

indicating that the payment has been successful.

If the 3D-Secure flow is needed, the response will be like:

{
  "action": {
    "action_type": "redirect",
    "url": "https://issuer.acme.com/1JsQ8gdJX6PwRZJOg5JXg8gKyU"
  },
  "objects": {
    "payment_uuid": "009ff9b8-b08f-48d6-b973-fc7d9ca1e64c",
    "payment_status": "pending",
    "reason": "pending"
  }
}

The user must be redirected to action.url and complete all steps. Afterwards, the user will be redirected to https://futurogoal.raisenow.com/payments?payment_uuid=009ff9b8-b08f-48d6-b973-fc7d9ca1e64c&status=pending&reason=pending as initially instructed in request_url.

SEPA Direct Debit

SEPA Direct Debit is a Europe-wide Direct Debit system that allows merchants to collect Euro-denominated payments from accounts in the SEPA countries and associated territories.

SEPA Direct Debit is a reusable, delayed notification payment method. This means that it can take up to 14 business days to receive notification on the success or failure of a payment after you initiate a debit from the supporter’s account, although the average is five business days.

In order to charge an account, supporters must provide their bank account details, including their IBAN and billing address details within the payment form during the checkout flow. The bank account holder is then required to accept a mandate to authorize RaiseNow's partners to debit their account. This payment method requires that the mandate's terms are set out on the same page as where the supporter enters their bank account details. The mandate should make it clear that if the supporter submits their bank account details to RaiseNow partners, they are implicitly agreeing to the mandate.

Create a SEPA Direct Debit Payment

To create a SEPA Direct Debit Payment the request payload should contain the supporter's bank account IBAN in the payment_information section:

{
    "iban": "string"
}

And the billing address details in the supporter section:

{
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "city": "string",
  "country": "ISO 3166-1 alpha-2 string",
  "street": "string",
  "postal_code": "string"
}

A complete example SEPA Direct Debit Payment is:

{
  "account_uuid": "fb5683e4-5629-4626-9d76-b81139bc673c",
  "profile": "09bed958-0eab-4c42-b026-ee34cdad02a9",
  "test_mode": true,
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "payment_information": {
      "iban": "DE08370400440532013003"
  },
  "supporter": {
      "first_name":"First Name",
      "last_name":"Last Name",
      "email":"email@test.com",
      "city": "Berlin",
      "country": "DE",
      "street": "Street",
      "postal_code":"1234"
  }
}

Please notice that the absence of any of the aforementioned payload arguments will result in a validation error.

To store the Payment Information in a Payment Source for future usage, a top-level argument create_payment_source in the payment request payload should be set to true.

Subscriptions can be used to create regular charges from a supporter's bank account.

Activate SEPA Direct Debit

SEPA Direct Debit is not enabled by default in Stripe, and activation can be requested only 30 to 60 days after the first credit card payments. To do so, please head to the page Payment Method Settings in your Stripe dashboard.

RaiseNow will automatically detect when Stripe has enabled SEPA Direct Debit on your account.

For further inquiries about the activation process and timeline, please contact Stripe directly.

Receive a notification about Payment Status

SEPA Direct Debit is a delayed notification payment method, and it can take up to 14 days for a Payment to succeed or fail. We recommend using Webhooks to get notified when a Payment status changed.

The following events are sent when the Payment status is updated:

Event	Description
raisenow.payments.payment.succeeded	The supporter’s payment succeeded.
raisenow.payments.payment.failed	The supporter’s payment was declined.

Creditor Identifiers

A SEPA Creditor Identifier (Creditor ID) is an ID associated with each SEPA Direct Debit payment that identifies the company requesting the payment. Whilst companies may have multiple creditor identifiers, each creditor identifier is unique and allows your customers to easily identify the debits on their account.

By default, your Stripe account is configured to use a Stripe Creditor ID when collecting SEPA Direct Debit Payments. Stripe Payments will appear on bank statements.

If you’re based in the EU, RaiseNow recommends that you use your own Creditor ID to both reduce dispute rates and improve your supporter experience. You can configure your own Creditor ID on the Payment Method Settings page in your Stripe dashboard.