Skip to content

Latest commit

 

History

History
92 lines (76 loc) · 5.31 KB

api-payments.md

File metadata and controls

92 lines (76 loc) · 5.31 KB

Census API: Payments

Order creation

📍 Creates an order for a person. It can use an existing payment method or can create a new one.

POST api/v1/payments/orders
Parameter Data type Description Only when payment_method_type is ...
person_id string Person's qualified identifier
description string Order description
amount integer Order amount (in cents, 1000 will be 10.00€)
campaign_code string Unique identifier for the campaign related to the order
payment_method_type string existing_payment_method, direct_debit or credit_card_external
payment_method_id integer Payment method identifier at Census existing_payment_method
return_url string After payment back URL (string must include __RESULT__ that will be replaced by ok or ko) credit_card_external
iban string Normalized bank account's IBAN (no speces or symbols, only letters and numbers) direct_debit

Return value

  • When the order is successfully created, server response will be :created (HTTP 201) and a JSON with the used payment method identifier in the payment_method_id key.
  • When using credit_card_external payment method, server response will be :accepted (HTTP 202) and the JSON will also include the form key, with information to generate a page with a <FORM> tag that should be sumbitted to the payment gateway. This form could be submitted automatically with JavaSscript or could present a summary of the payment and a submit button to proceed. This hash will contain two keys:
    • action is the URL where the form should be submitted
    • fields is a Hash with key/value pairs that should be included in the form with hidden input fields.
  • When the given parameters for the order, server response will be :unprocessable_entity (HTTP 422) and a JSON with the errors for each parameter.
  • When there is an error creating the order, server response will be :server_internal_error (HTTP 500).

Totals

📍 Returns total amount for processed orders for a campaign and/or a person. Also they can be filtered by a span of time.

GET api/v1/payments/orders/total
Parameter Data type Description
campaign_code string Optional. Unique identifier for the campaign
person_id string Optional. Person's qualified identifier
from_date datetime Optional. Include orders created after this date (use ISO datetime format)
until_date datetime Optional. Include orders created before this date (use ISO datetime format)

Return value

  • Server response will be :ok (HTTP 200) and a JSON with the amount key.
  • Person or campaign filter should be used, server response will be :unprocessable_entity (HTTP 422) otherwise.

Payment methods retrieval

📍 Retrieves all the payment methods for a person.

GET api/v1/payments/payment_methods
Parameter Data type Description
person_id string Person's qualified identifier

Return value

  • When the person exists in the database, server response will be :ok (HTTP 200) and a JSON with all the payment methods related to that person: (fields id.
Parameter Data type Description
id integer Payment method identifier at Census
name string Payment method human name
type string Payment method type: PaymentMethods::DirectDebit or PaymentMethods::CreditCard
status string Payment method status: incomplete, active or inactive
verified? boolean Was the payment method successfuly used before?
  • When there is no person for the given person_id, server response will be :unprocessable_entity (HTTP 422) and an empty JSON.
  • The verified status is different from active

Payment method retrieval

📍 Retrieve a payment method information.

GET api/v1/payments/payment_methods/:id
Parameter Data type Description
id integer Payment method identifier at Census

Return value

  • When the payment method exists in the database, server response will be :ok (HTTP 200) and a JSON with the payment method information: (fields id.
Parameter Data type Description
id integer Payment method identifier at Census
name string Payment method human name
type string Payment method type: PaymentMethods::DirectDebit or PaymentMethods::CreditCard
status string Payment method status: incomplete, active or inactive
verified? boolean Was the payment method successfuly used before?
  • When there is no payment method for the given id, server response will be :not_found (HTTP 404) and an empty JSON.