Canopy API - Latest

Execute a payment attempt for a specific account with arbitrary payment method

POST /accounts/{account_id}/line_items/payments/guest_payment

Canopy will first try to execute a payment via the supplied payment method, and then store the corresponding record in Canopy's system.

Path parameters

account_id string Required

ID of the Account

Body object Required

Body of request to create guest payment.

line_item_id string

The ID to be associated with the line item for future requests.

Format should match the following pattern: ^(?!can_).*$.
effective_at string(date-time)

The Date-Time that the payment is applicable to the account. This field should only be used to back-date payment transactions for the purpose of testing or if a data migration is being performed with migration_mode enabled.
original_amount_cents integer Required

The payment amount in cents.

Default value is 0.
payment_details object Required
- payment_type string Required
  
  The type of payment details provided.
  
  Value is ACH.
- payment_processor_name
  
  The name of the payment processor to be used.
  
  Value is CANOPY_NACHA.
- bank_account_number string Required
  
  The corresponding account number for the bank account to be used for payment.
- bank_routing_number string Required
  
  The corresponding routing number for the bank account to be used for payment.
  
  Minimum length is 9, maximum length is 9.
- standard_entry_class string
  
  The value to use for the standard entry class in ACH files. 'TEL' signifies the payment authorizations granted orally over phone. 'WEB' signifies authorizations granted over web apps.
  
  Values are WEB or TEL.
external_fields object | null

External fields can be used to relate payments created in Canopy to entities in your or any external system.

line_item_id string

The ID to be associated with the line item for future requests.

Format should match the following pattern: ^(?!can_).*$.
effective_at string(date-time)

The Date-Time that the payment is applicable to the account. This field should only be used to back-date payment transactions for the purpose of testing or if a data migration is being performed with migration_mode enabled.
original_amount_cents integer Required

The payment amount in cents.

Default value is 0.
payment_details object Required
- payment_type string Required
  
  The type of payment details provided.
  
  Value is DEBIT.
- payment_processor_name
  
  The name of the payment processor to be used.
  
  Value is AUTHORIZE_NET.
- name string Required
  
  The corresponding name on the the debit card to be used for payment.
- card_number string Required
  
  The corresponding card number for the debit card to be used for payment.
  
  Minimum length is 16, maximum length is 16.
- expiration_date string(date) Required
  
  The corresponding expiration date for the debit card to be used for payment in MM/YY format.
- cvv string Required
  
  The corresponding card verification value for the debit card to be used for payment.
  
  Minimum length is 3, maximum length is 4.
- zip string Required
  
  The corresponding postal code for the debit card to be used for payment.
  
  Minimum length is 2.
external_fields object | null

External fields can be used to relate payments created in Canopy to entities in your or any external system.

Responses

• 422

Invalid input.
• 429

Too many requests.
• default

Unexpected Error.
• 200 object

Payment created
- merchant_data object | null
  
  Merchant information if applicable.
  name string
  
  id string
  
  mcc_code number
  
  phone_number string
- issuer_processor_details object | null
  lithic object
  
  last_four string | null
  
  Last four digits of the card against which the spend was made.
  
  transaction_token string(uuid) | null
  
  The external unique identifier of the transaction.
  
  card_token string(uuid) | null
  
  The external unique identifier of the card related to this line item.
- external_fields array[object] | null
  
  An array of static references to fields in a third party system.
  
  Not more than 1000 elements.
  key string
  
  Key - i.e. Name of the External Party
  
  value string
  
  Value - i.e. External Account ID
- line_item_overview object
  line_item_status string
  
  The new status which you would like to set for the line item
  
  Values are VALID, INVALID, PENDING, or AUTHORIZED. Default value is VALID.
  
  line_item_type string Required
  
  The line item type PAYMENT
  
  Default value is PAYMENT.
  
  description string | null
  
  A description of this particular line item if any. More common for adjustments.
- Additional properties are allowed
- account_id string Required
  
  The account associated with the line item
- line_item_id string Required
  
  The ID associated with the line item
- effective_at string(date-time)
  
  The Date-Time that this line item became/becomes active
- created_at string(date-time)
  
  The Date-Time which the line item was created.
- product_id string Required
  
  the Product ID of the account
- line_item_summary object
  balance_cents integer
  
  The current balance of the line item, which accounts for interest accrued per the product's interest policy and the account's interest rate attribute.
  
  principal_cents integer
  
  The principal balance of the line item.
  
  interest_balance_cents integer
  
  The current interest balance of the line item.
  
  am_interest_balance_cents integer
  
  The current AM interest balance of the line item. Canopy tracks interest during an amortization period separately from deferred interest accrued during a revolving period.
  
  deferred_interest_balance_cents integer
  
  The current deferred interest balance of the line item.
  
  am_deferred_interest_balance_cents integer
  
  The current AM deferred interest balance of the line item. Canopy tracks deferred interest during an amortization period separately from deferred interest accrued during a revolving period.
  
  total_interest_paid_to_date_cents integer
  
  The sum (in cents) of all payments towards interest charges, if any, applied to this line item to date
  
  original_amount_cents integer
  
  The originating amount of money (in cents) relating to this line item.

POST /accounts/{account_id}/line_items/payments/guest_payment

curl \
 -X POST https://<your_environment_name>-uat-api.canopyservicing.com/accounts/can_52322/line_items/payments/guest_payment \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"line_item_id":"0x1234","effective_at":"2020-07-20T09:11:28+00:00","original_amount_cents":200,"payment_details":{"payment_type":"ACH","payment_processor_name":"CANOPY_NACHA","bank_account_number":"1234","bank_routing_number":"021000021","standard_entry_class":"WEB"},"external_fields":{}}'

Request examples

{
  "line_item_id": "0x1234",
  "effective_at": "2020-07-20T09:11:28+00:00",
  "original_amount_cents": 200,
  "payment_details": {
    "payment_type": "ACH",
    "payment_processor_name": "CANOPY_NACHA",
    "bank_account_number": "1234",
    "bank_routing_number": "021000021",
    "standard_entry_class": "WEB"
  },
  "external_fields": {}
}

{
  "line_item_id": "0x1234",
  "effective_at": "2020-07-20T09:11:28+00:00",
  "original_amount_cents": 200,
  "payment_details": {
    "payment_type": "DEBIT",
    "payment_processor_name": "AUTHORIZE_NET",
    "name": "string",
    "card_number": "4007000000027",
    "expiration_date": "12/00",
    "cvv": "123",
    "zip": "12345"
  },
  "external_fields": {}
}

Response example (200)

{
  "account_id": 4,
  "line_item_id": 2,
  "effective_at": "2018-07-20T09:12:30+00:00",
  "created_at": "2018-06-20T09:12:30+00:00",
  "product_id": 1,
  "line_item_summary": {
    "original_amount_cents": 2484,
    "balance_cents": 3600,
    "principal_cents": 2400,
    "interest_balance_cents": 1100,
    "am_interest_balance_cents": 0,
    "deferred_interest_balance_cents": 200,
    "am_deferred_interest_balance_cents": 0,
    "total_interest_paid_to_date_cents": -16
  },
  "merchant_data": {
    "name": "string",
    "id": "string",
    "mcc_code": 42.0,
    "phone_number": "string"
  },
  "issuer_processor_details": {
    "lithic": {
      "last_four": 3324,
      "transaction_token": "33xd08bc-d100-488y-bb93-f8a1f081ff0e",
      "card_token": "c6cd08bc-c524-48f5-b64d-f79ec0810df4"
    }
  },
  "external_fields": [
    {
      "key": "Globex Card Processing Account ID",
      "value": "22445702-a389-431f-927d-07b8d0750787"
    }
  ],
  "line_item_overview": {
    "line_item_status": "VALID",
    "line_item_type": "PAYMENT",
    "description": "Payment against the account"
  }
}