👍

Note:

The field will be disregarded if it is marked as optional and the format provided is incorrect. However, a validation error will be displayed if the field is marked as mandatory and the format provided is incorrect.

"+" - means required (for all flows)
"-" - means not required (for any flow)
For instance, in POST Create Charge flow:
+6 means that the field is required for flow number 6
-6 means that the field is not required for flow number 6


Charges

A сharge is a one-time payment that can be requested against any connected processing service.

Charges can be created through one of the following payment instruments at PowerBoard. Charges can have different states (i.e. when used within a 3DS ) and can be manipulated based on the various states.


Conditions

The response is different depending on the following conditions:

  1. Created with a credit card payment source
  2. Created with an existing customer
  3. Created by a subscription
  4. Processed on a gateway with a failed status
  5. Pre-auth charge
  6. Charge with a pre-auth charge_id
  7. Created with a vault token
  8. Created with a checkout payment source type

    Charge Resource

fieldrequired[flow]typedescription
amount+floatAn amount of the payment
currency+string (iso4217 alpha-3)A currency code
description-stringA manually defined description for payments in payment systems
reference-stringA manually defined reference for payments in payment systems
_id+string (24 hex characters)A charge ID for any future requests
external_id+stringAn external ID of the transaction
created_at+string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ)A charge creation date
updated_at+string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ)A date of the last charge update
user_id-string (24 hex characters)An ID of an initiator of the request if the request was made by the personal token (from the dashboard)
status+stringAn actual charge status. See the status table
capture+boolDefines if the charge is automatically captured or only authorized
authorization+boolDefines if the charge followed authorization flow
one_off+boolFor manual charges, it is always true; for subscriptions, it is always false
archived+boolFor newly created charges, it is always false, it is set to true after manual archivation
_source_ip_address+stringThe IP address of the initiator of the request, for subscription, it is 127.0.0.1 by default
subscription_id+3string (24 hex characters)A subscription ID
customer+objectAn object with the customer’s information
customer.customer_id+2string (24 hex characters)A customer ID
customer.first_name-stringA customer's first name
customer.last_name-stringA customer's last name
customer.email-stringA customer's email
customer.phone-string(E.164)A customer's phone in the E.164 international notation (Example: +12345678901)
customer.payment_source+objectAn object with payment information
customer.payment_source.source_id+2, -3string (24 hex characters)A payment source ID
customer.payment_source.gateway_id+string (24 hex characters)A gateway ID
customer.payment_source.vault_token+7string (uiid)A vault token ID
customer.payment_source.gateway_type+stringA type of the gateway
customer.payment_source.gateway_name+stringA custom name of the gateway
customer.payment_source.type+stringA type of the payment: card for payments with credit card, bank_account for direct debit payments, checkout for payments with a checkout agreement (checkout button) , ), wallet for payments with a wallet source (Apple/Google Pay, Paypal Smart Button )
customer.payment_source.card_name+1stringA cardholder's name (as on card)
customer.payment_source.card_number_last4+1string(numeric)Card number last 4
customer.payment_source.card_number_bin+1string(numeric)Card BIN number
customer.payment_source.card_scheme+1stringA cardholder's scheme (i.g. visa, mastercard etc...)
customer.payment_source.expire_month+1string(mm)Card expiration month
customer.payment_source.expire_year+1string(yyyy)Card expiration year
customer.payment_source.card_holder_accept_method-stringThe mechanism the cardholder used to accept the details
customer.payment_source.card_accept_type-stringThe type the cardholder used to accept the details
customer.payment_source.checkout_email+8stringThe email that was applied for the checkout agreement
customer.payment_source.checkout_holder+8stringThe holder name of the account or wallet that was applied for the checkout agreement
customer.payment_source.external_payer_id+8stringThe ID of a payer that was applied for the checkout agreement
customer.payment_source.address_line1-stringA customer's address, line 1
customer.payment_source.address_line2-stringA customer's address, line 2
customer.payment_source.address_state-stringA customer's address, state
customer.payment_source.address_country-stringA customer's address, country code
customer.payment_source.address_city-stringA customer's address, city
customer.payment_source.address_postcode-stringA customer's address, postcode
transactions+arrayAll transactions within the charge
transactions[]._id+string(24 hex characters)An internal ID of the transaction
transactions[].external_id+stringAn identifier of a transaction on a gateway side
transactions[].external_reference+stringAn additional reference of a transaction on a gateway side
transactions[].amount+floatAn amount of the transaction
transactions[].amount_fee+floatAn amount fee of the transaction
transactions[].currency+string (iso4217 alpha-3)A currency code of the transaction
transactions[].type+stringA type of the transaction: Look at transaction types table
transactions[].status+stringA status of the transaction: Look at transaction status table
transactions[].created_at+string(ISO 8601 format - yyyy-mm-ddThh:mm:ss.sssZ)A transaction creation date
transactions[].gateway_specific_code+4stringAn error code on the gateway side
transactions[].gateway_specific_description+stringAn internal or external error message
transactions[].error_message+4stringAn internal error message
transactions[].error_code+4stringAn internal error code
transactions[].custom_fields-objectThe object of custom fields for a transaction. These fields are sent to the gateway if this option was enabled when the gateway was created or modified
transactions[].custom_fields.any-stringThese fields can have any custom name and value
transactions[].descriptor-stringA descriptor of a transaction
transactions[].channel_id-1, -2, -5, -7stringChannel identifier
transactions[].wallet_id-1, -2, -5, -7stringWallet identifier
transactions[].card_acceptor-1, -2, -5, -7objectContact information identifying the location from which the money transfer originates
transactions[].card_acceptor.address_city-1, -2, -5, -7stringCard acceptor address city
transactions[].card_acceptor.address_company-1, -2, -5, -7stringCard acceptor address company
transactions[].card_acceptor.address_postcode-1, -2, -5, -7stringCard acceptor address postcode
transactions[].card_acceptor.address_country-1, -2, -5, -7stringCard acceptor address country
transactions[].card_acceptor.address_state-1, -2, -5, -7stringCard acceptor address state
transactions[].card_acceptor.address_line1-1, -2, -5, -7stringCard acceptor address line 1
transactions[].card_acceptor.address_line2-1, -2, -5, -7stringCard acceptor address line 2
transactions[].card_acceptor.name-1, -2, -5, -7stringCard acceptor name
transactions[].card_acceptor.phone-1, -2, -5, -7stringCard acceptor phone
meta-objectAn optional object with specific fields for different gateways

Status

status description
completeA charge is successful
pending A charge awaits capture or cancel
requested A charge was requested, but the gateway did not return the actual status (it is usually relevant for bank account transactions). The status will be updated later automatically by the schedule task
failed The charge failed (see details of an error)
refund_requested A refund was requested, but the gateway did not return the actual status (it usually requires some time). The status will be updated later automatically by the schedule task or manually by the specific endpoint
void_requested A void was requested, but the connected service did not return the actual status. The status will be monitored by PowerBoard until a result is returned. It can also be manually checked
capture_requested A capture was requested, but the connected service did not return the actual status. The status will be monitored by PowerBoard until a result is returned
refund_void_requested A refund void was requested, but the connected service did not return the actual status. The status will be monitored by PowerBoard until a result is returned. It can also be manually checked
refunded A refund is successful
inprogress An intermediate status, short-lived
held A type of charges created by subscriptions with the status 'held'
not_authenticated Pre-auth (3ds) is not supported for such card
pre_authenticated Pre-auth (3ds) is created successfully and accepted by the user
pre_authentication_pending Pre-auth (3ds) is created successfully and awaits to be accepted by the user
refund_declined A charge refund was declined
cancelled A charge was cancelled

Transaction types

typedescription
saleA payment transaction
refundA refund transaction
cancelA cancel (void) transaction for reversing a payment before it is settled
captureA capture transaction for securing a payment after its authorisation
walletA transaction processed with a WalletButton widget
initializationA transaction used to initialize wallet flow
verificationA verification transaction

Transaction status

statusdescription
completeA complete direct or captured transaction
failedA failed transaction or refund
inprogressA system state of a transaction while it is sending a request to a payment gateway
pendingAn authorized but not captured transaction
capture_requestedA capture was requested, but the connected service did not return the actual status. The status will be monitored by PowerBoard until a result is returned
requestedA refund pending status. After an automatic scheduled transaction check, it might go to 'complete' or 'failed'
cancelledA cancelled transaction