WePay logo
      Nothing Found

Create a payment

post/payments

The POST /payments call allows your platform to create a new payment. For platforms on blended rate pricing leveraging the Clear product, remember to appropriately calculate fees. To try this request out in the console, update the following parameters with your own information: App-Id, App-Token, Unique-Key, payment_method.

SecurityappIdAuth and appTokenAuth
Request
header Parameters
Api-Version
required
string
Example: 3.0
Content-Type
required
stringapplication/json
Example: application/json
Unique-Key
required
string
WePay-Risk-Token
string

This header is required when tokenizing Payment Methods, Legal Entities, and Payout Methods when the tokenization JS library is not being used.

Client-IP
string

This header is required when tokenizing Payment Methods, Legal Entities, and Payout Methods when the tokenization JS library is not being used.

Request Body schema: application/json
amount
required
integer >= 100

Amount in the lowest denomination. For example, $1.00 is represented as 100. This applies to all currencies WePay supports.

currency
required
string

ISO 4217 currency code. Possible values include: CAD & USD. Note: as of today, currency supports a single value.

Enum: Description
USD

United States Dollar

CAD

Canadian Dollar

… 1 more
account_id
required
string

Merchant's account id associated with the payment.

required
object

The payment method used to create this payment.Note: The payment method's top level data object corresponds with the payment method type. For example, if you set type to credit_card, then the payment method's top level data object must be credit_card.

auto_capture
boolean

For payments with a credit card payment method, set to false to create a delayed-capture payment. Capture the payment within 7 days with the POST /payments/{id}/capture endpoint. Alternatively, cancel the payment with the POST /payments/{id}/cancel endpoint.

capture_at
integer or null

Designate the time at which this payment will capture using a UNIX epoch timestamp. The capture time cannot be more than 7 days in the future. Note that epoch timestamps use the UTC timezone.

object or null

Any custom data your platform chooses to attach to this resource. The custom data must be key-value pairs and not contain any personally identifiable information (PII) or payment card (PCI) data.

fee_amount
integer >= 0

Specifies the fee amount your platform will collect from the payment. The amount should be in the lowest denomination. For example, $1.00 is represented as 100. This applies to all currencies WePay supports. Note: The upper limit for the fee amount is 20% of the payment. If this field is blank and the merchant is on blended pricing, $0 will be debited from the merchant and credited to your platform account, but WePay’s fees will still be debited from your platform account. Remember to appropriately calculate fees. Payments for merchants on MIC+ should leave this field blank as fees are assessed monthly rather than per transaction. If any number other than 0 is passed it will be ignored, and 0 will be applied and returned.

initiated_by
string

Indicates who initiated a payment. Possible values include: customer, merchant, null. Note: This parameter defaults to none when creating a payment unless a credit card payment method has "card_on_file": "true". "Card on file" payments default to customer. For recurring credit card payments: this parameter should be set to customer on the first transaction, and then on subsequent recurring transactions, this parameter should be set to merchant. This parameter is not used for recurring ACH payments.

Enum: Description
customer
merchant
object
order_id
string or null [ 1 .. 255 ] characters

The resource ID of the order that your app associated with this payment. If no order was associated, then the value will be null.

Array of objects or null

Any rbit data your platform chooses to attach to this resource. The rbit data must be key-value pairs and can be an array of rbit objects.

reference_id
string or null [ 1 .. 255 ] characters

A custom reference ID for your platform to track the object. It can be any string.

Responses
201
Response Schema: application/json
id
required
string or null

ID of the payment, generated by WePay when the payment is created.

resource
required
string

Helps organize information by identifying the resource type of the object data.

Value: Description
payments
path
required
string

The HTTP path of the resource. The path can be used to retrieve details about the resource and perform actions on it.

required
object or null

Details the owner resource and owner path.

create_time
required
integer <int64> >= 0

The UNIX timestamp for when the object was created.

status
required
string

Status of the payment. Possible values include: canceled completed, failed, pending.

Enum: Description
pending

This payment is processing, but is not yet included in the account's available or reserve balance. Find more information in the pending_reasons structure.

completed

This payment has finished processing, and is now available in either the account's available or reserved balance. Note: A payment can have a completed status and simultaneously have a refund or dispute issued against it.

… 2 more
amount
required
integer

Amount in the lowest denomination.

amount_refunded
required
integer
amount_disputed
required
integer
currency
required
string

ISO 4217 currency code. Possible values include: CAD & USD. Note: as of today, currency supports a single value.

Enum: Description
USD

United States Dollar

CAD

Canadian Dollar

… 1 more
required
object
initiated_by
required
string

Indicates who initiated a payment. Possible values include: customer, merchant, none.

Enum: Description
customer
merchant
… 1 more
reference_id
required
string or null [ 1 .. 255 ] characters

A custom reference ID for your platform to track the object. It can be any string.

capture_at
required
integer or null <int64> >= 0

For payments with a credit card payment method, designate the time at which this payment will capture using a UNIX epoch timestamp. The capture time cannot be more than 7 days in the future. Note that epoch timestamps use the UTC timezone.

authorization_code
required
string or null

Authorization code returned from the card issuer after a credit card payment is authorized

api_version
string
auto_capture
boolean

For payments with a credit card payment method, set to false to create a delayed-capture payment. Capture the payment within 7 days with the POST /payments/{id}/capture endpoint. Alternatively, cancel the payment with the POST /payments/{id}/cancel endpoint.

object or null

Any custom data your platform chooses to attach to this resource. The custom data must be key-value pairs and not contain any personally identifiable information (PII) or payment card (PCI) data.

object or null
fee_amount
integer

Specifies the fee amount your platform will collect from the payment. The amount should be in the lowest denomination. Note: Platforms leveraging the blended rate pricing model should use this parameter. This parameter is not applicable to platforms leveraging the Merchant IC+ pricing model.

object or null

The resource ID and path for the Order that your app created and associated with the payment.

Array of objects or null

Explains why this payment is pending and may contain an array of reasons.

object or null

Fetch this transaction record to account for the portion of this transaction which impact your application balance.

object or null

Fetch this transaction record to account for the merchant's portion of this transaction.

400

INVALID_PARAMS, MERCHANT_ACCOUNT_CANNOT_ACCEPT_PAYMENTS, TRANSACTION_DECLINED, UNSUPPORTED_CURRENCY

403

NOT_AUTHORIZED

500

UNEXPECTED_ERROR

Request samples
application/json
{
  • "account_id": "abc123",
  • "amount": 1000,
  • "auto_capture": true,
  • "currency": "USD",
  • "custom_data": {
    • "my_key": "invoice #54321"
    },
  • "fee_amount": 30,
  • "payment_method": {
    • "credit_card": {
      • "auto_update": false,
      • "card_holder": {
        • "address": {
          • "city": "Redwood City",
          • "country": "US",
          • "line1": "350 Convention Way",
          • "postal_code": "94025",
          • "region": "CA"
          },
        • "email": "example@wepay.com",
        • "holder_name": "John Snow"
        },
      • "card_number": "5496198584584769",
      • "cvv": "007",
      • "expiration_month": 4,
      • "expiration_year": 2030,
      • "virtual_terminal_mode": "web",
      • "card_on_file": true,
      • "recurring": false
      },
    • "custom_data": {
      • "my_key": "invoice #54321"
      },
    • "type": "credit_card"
    },
  • "initiated_by": "customer",
  • "reference_id": "dfeb052b-ae8c-4a69-b909-8d9ecdd7c742"
}
Response samples
application/json
{
  • "amount": 1000,
  • "amount_refunded": 1000,
  • "amount_disputed": 1000,
  • "auto_capture": false,
  • "capture_at": null,
  • "create_time": 1510080179,
  • "currency": "USD",
  • "custom_data": null,
  • "failure_reason": null,
  • "fee_amount": 0,
  • "id": "00000000-0000-0000-0000-0000767bf5cd",
  • "order": null,
  • "owner": {
    • "id": "be2b42e5-b808-40ae-9bbe-3291ab493f57",
    • "path": "/accounts/be2b42e5-b808-40ae-9bbe-3291ab493f57",
    • "resource": "accounts"
    },
  • "path": "/payments/00000000-0000-0000-0000-0000767bf5cd",
  • "payment_method": {
    • "id": "00000000-6363-0000-0000-000008b93a6e",
    • "path": "/payment_methods/00000000-6363-0000-0000-000008b93a6e",
    • "resource": "payment_methods"
    },
  • "pending_reasons": [
    • {
      • "details": [ ],
      • "reason_code": "PENDING_CAPTURE",
      • "reason_message": "Payment pending capture."
      }
    ],
  • "resource": "payments",
  • "status": "pending",
  • "authorization_code": "0224241",
  • "txnr_app_fee": null,
  • "txnr_merchant": null,
  • "initiated_by": "customer",
  • "api_version": "3.0",
  • "reference_id": "dfeb052b-ae8c-4a69-b909-8d9ecdd7c742"
}