Process Payments

 

At this point you have onboarded your merchants and met the requirements to enable Payment and Payout capabilities. Now you'll process a Payment from a payer to the merchant's WePay Account. The Clear Payment APIs allow you to build a secure, simple payment flow, and lets you describe different user experience journeys for Payments, Refunds, and Disputes.

As part of the integration, you'll be required to certify your payment processing infrastructure with specific attention to card network rules, NACHA rules and regulations pertaining to ACH and eCheck payments, and security. Use the following guides to ensure that your integration is compliant:

Calculate Fees

Partners on Blended with Merchants on Blended
First, we'll review how fees work so you can manage your platform's monetization regardless of the components you use for Payments.
Warning
The fee-collection method described here is geared towards Blended Rate pricing. Fees will work differently for your platform if you are implementing Merchant IC+ pricing.
When you create a Payment, you'll define the total amount of fees that you will collect from it with the fee_amount parameter. The net (amount minus fee_amount) will be deposited into your merchant's WePay Account, and the fees will be deposited into your platform's WePay partner account. Next, we will debit processing fees from your WePay partner account. This means that when you create a payment and define fees, the value should be a sum of your platform's fees and our processing fees.As an example, let's say that your contract with WePay has set credit card transaction fees at 3% + $0.30 per transaction. In addition, your platform charges $1.00 per transaction. If you then created a credit card payment for $100.00, you should calculate fees as: (3% of the amount) + $1.30. Thus, the value you would send for the fee_amount parameter would be 430.
Note
Fee amounts are notated in cents, so 430 represents $4.30.

The net that your merchant receives will be $95.70, and your platform will receive the full fee amount. We will then debit your platform WePay Account for the processing fees agreed to. Following the example above, your platform's net would be $1.00, and WePay would debit $3.30 from you.

Partners on IC+
Partners on Partner IC+ should calculate fee_amount assuming that fees will never be higher than 2.9% + $0.30.

Charging a Variable Fee

If charging a variable fee in addition to a flat rate, as opposed to just a $1 flat rate, (e.g. charging 2.65% + $0.20), be sure to calculate the fee_amount as your variable and flat fees added to our variable and flat fees. Let's work with the same basic example as above; your contract with us has set credit card transaction fees at 3% + $0.30 per transaction and you are calculating fees for a $100.00 transaction. You want to earn 2.65% + $0.20 per transaction.

First, calculate our fees: (3% of $100) + $0.30 = $3.30.

Next, calculate your own fees: (2.65% of $100) + $0.20 = $2.85.

Finally, the total fees debited from the merchant will be $3.30 + $2.85 = $6.15, which must be sent in the fee_amount parameter as 615.Be sure to review Card Network Rules on fees in order to charge fees in a compliant manner.

Use Payment Method Tokens

To immediately create a Payment, we'll send a POST request to the /payments endpoint. Before we get into the body of the call, we're going to add a Unique-Key to the header, so that a Payment can't execute twice. The value can be anything as long as it's unique.
credit card tokenpayment bank token
Copy
Copied
curl -X POST \
  --url 'https://stage-api.wepay.com/payments' \
  -H 'App-Id: {your-app-id}'\
  -H 'App-Token: {your-app-token}'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json'\
  -H 'Unique-Key: {generate-a-unique-key}' \
  --data-raw '{
"account_id": "{merchant's-account-id}",
"amount": 1000,
"currency": "USD",
"payment_method": {
    "token": {
        "id": "payment_methods-YOUR-TOKEN-HERE"
        },
    "credit_card": {
        "card_holder": {
        "holder_name": "Test Test",
        "email": "foo@bar.com",
            "address": {
                "country": "US",
                "postal_code": "94025"
            }
        }
    }
},
“fee_amount”: 200
}'
Copy
Copied
curl -X POST \
  --url 'https://stage-api.wepay.com/payments' \
  -H 'App-Id: {your-app-id}'\
  -H 'App-Token: {your-app-token}'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json'\
  -H 'Unique-Key: {generate-a-unique-key}' \
  --data-raw '{
"account_id": "{merchant's-account-id}",
"amount": 1000,
"currency": "USD",
"payment_method": {
    "token": {
        "id": "payment_methods-YOUR-TOKEN-HERE"
        }
    }
},
Note the Unique-Key header, described in our Standard Headers and Idempotency articles. This header is required when creating Payments POST /payments and Refunds POST /refunds in order to protect against duplicate processing. Refer to the Risk Certification guide to identify standard required payment-level rBits and Risk Headers which will allow you to send us risk information about the payment. A payment may be flagged for manual risk review in which it is subject to 1-2 business days. The inclusion of payment-level rBits reduces the frequency and duration of manually reviewed payments as well as allows our Risk team to accurately action a payment.
Note
Retrieve the response body by sending a successful POST /payments request and then a second, identical POST /payments request with the same Unique-Key header.

Once you execute this call, you'll have successfully created a payment for the amount of $10, with a fee of $2, for a total of $8 going to the merchant. The $2 fee goes to you, as the platform. If the fee is not specified, the merchant receives $10 total.

Notes on Payments with Credit Card Tokens

  • First, we did not add auto_capture, because the default is true. The behavior of auto_capture being true means that WePay will execute the payment immediately. If you set auto_capture to false, you will need to capture it later, see Capture Authorized Payments below.
  • Second, the fee_amount allows the platform to set the fee for processing payment, with a hard limit of 20% of the transaction amount. In the above example, the amount to charge is 1000 ($10), and the fee is 200 ($2). We cap the fee at a maximum of 20% of the total amount. 201 ($2.01) wouldn't work, but 199 ($1.99) would.
  • In terms of processing, we will take the processing fee from the $2 (the default is 2.9% + $0.30 per transaction, but check with your WePay account manager for the most up to date fees), while the rest is given to your platform.
  • Lastly, although providing the cardholder information in both the POST /payments and POST /payment_methods requests are allowed, it is recommended that the cardholder information is provided in the POST /payments request. Providing the cardholder information in both the POST /payments and POST /payment_methods request will result in a TOKEN_CONFLICT response error.

This call will also convert the token into a Payment Method ID, which can be stored for future use.


Capture Authorized Payments

The above examples showcase payment flows where payment information is submitted and a payment is executed immediately upon the POST /payments call.

There are use cases where you'd like to authorize funds, but finalize payment at a later time (e.g., an item is purchased, but charged when shipped). There are a few different ways to go about this:

Partial capture is only available to US E-commerce platforms.

Note
The rules for capturing payments with Card Present transactions can be found here.

Manual Capture

By sending the POST /payments call with the auto_capture parameter set to false, you will delay the payment from moving to an account's available balance by keeping the status in pending. Note that the amount in the initial POST /payments request cannot be changed during capture.Next, make a POST /payments/id/capture request to capture that Payment which will update the API status to completed. Using the payment ID, a new Unique-key, and no POST body, the second POST call will look something like this
Copy
Copied
curl -X POST \
  --url 'https://stage-api.wepay.com/payments/id/capture' \
  -H 'Accept: application/json' \
  -H 'App-Id: {YOUR-APP-ID}' \
  -H 'App-Token: {YOUR-APP-TOKEN}' \
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json' \
  -H 'Unique-Key: {NEW-UNIQUE-KEY}' \
Note
The final capture amount cannot be greater than the initial authorized amount. If capturing less than the initial authorized amount, see the Partial Capture section below.
On a successful capture call, the payment status will become completed, and the funds will become available for Payout.

Deferred Capture

First, deferred capture has a few requirements, of which at least one must be met:

  • Any deferred capture Payment must be Card Present
  • Any deferred capture Payment which is not Card Present must meet one of the following:
    • Payment Method is a credit card sent in the payment_method.credit_card structure
    • Payment Method is a tokenized credit card sent in the payment_method.token structure

Deferred capture covers use cases where a card is authorized up-front for an estimated amount, and then the Payment is captured at a designated time. Deferred capture is designed to cover Card Present use cases, but can also be used by PCI compliant platforms where card data is securely stored on your platform's servers.

To schedule a deferred capture payment, send a POST /payments request with the capture_at parameter set with a value of the epoch timestamp of the desired capture time. If the timestamp is in the past, an API error will occur, and the time must be no more than 7 days in the future from the initial POST /payments request. Your request should look something like this:
Copy
Copied
curl -X POST \
  --url 'https://stage-api.wepay.com/payments' \
  -H 'Accept: application/json' \
  -H 'App-Id: {YOUT-APP-ID}' \
  -H 'App-Token: {YOUR-APP-TOKEN}' \
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json' \
  -H 'Unique-Key: {UNIQUE-KEY}' \
  --data-raw '{
  "capture_at": 1580803200,
  "account_id": "abc123",
  "amount": 1000,
  "currency": "USD",
  "fee_amount": 30,
  "payment_method": {
    "credit_card": {
      "auto_update": true,
      "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
    },
    "type": "credit_card"
  },
  "initiated_by": "customer"
}'
The API response will show a pending status until we automatically execute it at the time designated in the capture_at parameter. At that point, the Payment's status will either move to completed.Alternatively, you can manually capture the Payment before the time designated in the capture_at parameter. To do so, send a POST /payments/id/capture request at the desired capture time. The capture request should look like this:
Copy
Copied
curl -X POST \
  --url 'https://stage-api.wepay.com/payments/id/capture' \
  -H 'Accept: application/json' \
  -H 'App-Id: {YOUT-APP-ID}' \
  -H 'App-Token: {YOUR-APP-TOKEN}' \
  -H 'Api-Version: 3.0' \
  -H 'Content-Type: application/json' \
  -H 'Unique-Key: {NEW-UNIQUE-KEY}' \
Note
The final capture amount may be equal to or less than the initial amount authorized. The amount can also be updated up until the capture_at time.

Partial Capture

Another flow you may run into is partial captures, which is only available to US E-commerce platforms. Similar to the authorized payment example above, let's say a payer on your e-commerce platform purchases two items from a merchant. If that merchant is only able to ship one item, you can use a partial capture to execute the payment. Unlike capturing authorized payments, which require capturing the full amount, you can capture a partial amount. In the example below, we authorize $60 worth of goods, and partially capture $30 to finish the payment.

Note

While the final capture amount can be less, it cannot be greater than the initial authorized amount.

Start by sending a POST to /payments:
Copy
Copied
curl -X POST \
  --url 'https://stage-api.wepay.com/payments' \
  -H 'Accept: application/json' \
  -H 'App-Id: {YOUT-APP-ID}'\
  -H 'App-Token: {YOUR-APP-TOKEN}' \
  -H 'Api-Version: 3.0' \
  -H 'Content-Type: application/json' \
  -H 'Unique-Key: {UNIQUE-KEY}' \
  --data-raw '{
	"amount": 6000,
	"fee_amount": 300,
	"auto_capture": "false",
	"currency": "USD",
	"account_id": "account-id-here",
	"payment_method": {
		"token": {
			"id": "payment_methods-YOUR-TOKEN-HERE"
		}
	}
}'

Then, when ready to perform a partial capture, send a follow up call:

Copy
Copied
curl -X POST \
  --url 'https://stage-api.wepay.com/payments/id/capture' \
  -H 'Accept: application/json'\
  -H 'App-Id: {YOUT-APP-ID}'\
  -H 'App-Token: {YOUR-APP-TOKEN}'\
  -H 'Api-Version: 3.0'\
  -H 'Content-Type: application/json'\
  -H 'Unique-Key: {NEW-UNIQUE-KEY}' \
  --data-raw '{
	"amounts": {
		"amount": 3000,
		"currency": "USD",
		"fee_amount": 300
	}
}'

ACH

By default, ACH payments take 2 business days (excluding weekends and US holidays) to complete processing and be available to the merchant in a completed status. This window typically allows the issuing bank to process the request and send a response back to us. If the response from an issuing bank declines the payment and takes longer than 2 business days, then the payment will automatically be refunded.

CC Token

In order to create a payment which is captured at the time of creation, send a POST /payments request like so:
Loading...
Note the Unique-Key header, described in our Standard Headers and Idempotency articles. This header is required when creating Payments (POST /payments) and Refunds (POST /refunds) in order to protect against duplicate processing.
Note
Retrieve the response body by sending a second, identical POST /payments request with the same Unique-Key header.
The API response will contain a Payment Method ID which can be invoked for any future Payments from the same payer. Subscribe to the payment_method.updated topic to be notified when a credit card payment method expires, preemptively avoiding failed future Payments from the same Payer.

Inline CCs

When creating inline payment methods in a POST/payments request, the authorization minimum is $1, which you should include in the amount in the payment. There will be a $1 pending charge that will drop off in 7 days or if the payment is canceled before that.