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:
- Created with a credit card payment source
- Created with an existing customer
- Created by a subscription
- Processed on a gateway with a failed status
- Pre-auth charge
- Charge with a pre-auth charge_id
- Created with a vault token
- Created with a checkout payment source type
Charge Resource
| field | required[flow] | type | description |
|---|---|---|---|
| amount | + | float | An amount of the payment |
| currency | + | string (iso4217 alpha-3) | A currency code |
| description | - | string | A manually defined description for payments in payment systems |
| reference | - | string | A manually defined reference for payments in payment systems |
| _id | + | string (24 hex characters) | A charge ID for any future requests |
| external_id | + | string | An 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 | + | string | An actual charge status. See the status table |
| capture | + | bool | Defines if the charge is automatically captured or only authorized |
| authorization | + | bool | Defines if the charge followed authorization flow |
| one_off | + | bool | For manual charges, it is always true; for subscriptions, it is always false |
| archived | + | bool | For newly created charges, it is always false, it is set to true after manual archivation |
| _source_ip_address | + | string | The IP address of the initiator of the request, for subscription, it is 127.0.0.1 by default |
| subscription_id | +3 | string (24 hex characters) | A subscription ID |
| customer | + | object | An object with the customer’s information |
| customer.customer_id | +2 | string (24 hex characters) | A customer ID |
| customer.first_name | - | string | A customer's first name |
| customer.last_name | - | string | A customer's last name |
| customer.email | - | string | A customer's email |
| customer.phone | - | string(E.164) | A customer's phone in the E.164 international notation (Example: +12345678901) |
| customer.payment_source | + | object | An object with payment information |
| customer.payment_source.source_id | +2, -3 | string (24 hex characters) | A payment source ID |
| customer.payment_source.gateway_id | + | string (24 hex characters) | A gateway ID |
| customer.payment_source.vault_token | +7 | string (uiid) | A vault token ID |
| customer.payment_source.gateway_type | + | string | A type of the gateway |
| customer.payment_source.gateway_name | + | string | A custom name of the gateway |
| customer.payment_source.type | + | string | A 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 | +1 | string | A cardholder's name (as on card) |
| customer.payment_source.card_number_last4 | +1 | string(numeric) | Card number last 4 |
| customer.payment_source.card_number_bin | +1 | string(numeric) | Card BIN number |
| customer.payment_source.card_scheme | +1 | string | A cardholder's scheme (i.g. visa, mastercard etc...) |
| customer.payment_source.expire_month | +1 | string(mm) | Card expiration month |
| customer.payment_source.expire_year | +1 | string(yyyy) | Card expiration year |
| customer.payment_source.card_holder_accept_method | - | string | The mechanism the cardholder used to accept the details |
| customer.payment_source.card_accept_type | - | string | The type the cardholder used to accept the details |
| customer.payment_source.checkout_email | +8 | string | The email that was applied for the checkout agreement |
| customer.payment_source.checkout_holder | +8 | string | The holder name of the account or wallet that was applied for the checkout agreement |
| customer.payment_source.external_payer_id | +8 | string | The ID of a payer that was applied for the checkout agreement |
| customer.payment_source.address_line1 | - | string | A customer's address, line 1 |
| customer.payment_source.address_line2 | - | string | A customer's address, line 2 |
| customer.payment_source.address_state | - | string | A customer's address, state |
| customer.payment_source.address_country | - | string | A customer's address, country code |
| customer.payment_source.address_city | - | string | A customer's address, city |
| customer.payment_source.address_postcode | - | string | A customer's address, postcode |
| transactions | + | array | All transactions within the charge |
| transactions[]._id | + | string(24 hex characters) | An internal ID of the transaction |
| transactions[].external_id | + | string | An identifier of a transaction on a gateway side |
| transactions[].external_reference | + | string | An additional reference of a transaction on a gateway side |
| transactions[].amount | + | float | An amount of the transaction |
| transactions[].amount_fee | + | float | An amount fee of the transaction |
| transactions[].currency | + | string (iso4217 alpha-3) | A currency code of the transaction |
| transactions[].type | + | string | A type of the transaction: Look at transaction types table |
| transactions[].status | + | string | A 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 | +4 | string | An error code on the gateway side |
| transactions[].gateway_specific_description | + | string | An internal or external error message |
| transactions[].error_message | +4 | string | An internal error message |
| transactions[].error_code | +4 | string | An internal error code |
| transactions[].custom_fields | - | object | The 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 | - | string | These fields can have any custom name and value |
| transactions[].descriptor | - | string | A descriptor of a transaction |
| transactions[].channel_id | -1, -2, -5, -7 | string | Channel identifier |
| transactions[].wallet_id | -1, -2, -5, -7 | string | Wallet identifier |
| transactions[].card_acceptor | -1, -2, -5, -7 | object | Contact information identifying the location from which the money transfer originates |
| transactions[].card_acceptor.address_city | -1, -2, -5, -7 | string | Card acceptor address city |
| transactions[].card_acceptor.address_company | -1, -2, -5, -7 | string | Card acceptor address company |
| transactions[].card_acceptor.address_postcode | -1, -2, -5, -7 | string | Card acceptor address postcode |
| transactions[].card_acceptor.address_country | -1, -2, -5, -7 | string | Card acceptor address country |
| transactions[].card_acceptor.address_state | -1, -2, -5, -7 | string | Card acceptor address state |
| transactions[].card_acceptor.address_line1 | -1, -2, -5, -7 | string | Card acceptor address line 1 |
| transactions[].card_acceptor.address_line2 | -1, -2, -5, -7 | string | Card acceptor address line 2 |
| transactions[].card_acceptor.name | -1, -2, -5, -7 | string | Card acceptor name |
| transactions[].card_acceptor.phone | -1, -2, -5, -7 | string | Card acceptor phone |
| meta | - | object | An optional object with specific fields for different gateways |
Status
| status | description |
|---|---|
| complete | A 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
| type | description |
|---|---|
| sale | A payment transaction |
| refund | A refund transaction |
| cancel | A cancel (void) transaction for reversing a payment before it is settled |
| capture | A capture transaction for securing a payment after its authorisation |
| wallet | A transaction processed with a WalletButton widget |
| initialization | A transaction used to initialize wallet flow |
| verification | A verification transaction |
Transaction status
| status | description |
|---|---|
| complete | A complete direct or captured transaction |
| failed | A failed transaction or refund |
| inprogress | A system state of a transaction while it is sending a request to a payment gateway |
| pending | An authorized but not captured transaction |
| 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 |
| requested | A refund pending status. After an automatic scheduled transaction check, it might go to 'complete' or 'failed' |
| cancelled | A cancelled transaction |