Traffic Authentication
The Authorization Service requires the Basic Token in the header while the Transaction, Customer and Plan Services require a Bearer Token. All requests to the Authorization Service will need to point to the root endpoint or url https://auth.payfirma.com and requests to the other services will be addressed to https://apigateway.payfirma.com.
Get your Bearer Token
Step 1. Get your Client ID & Client Secret from your PayHQ account by going to Settings – eCommerce.
...
| Code Block |
|---|
Step 3.
curl https://auth.payfirma.com/oauth/token
--request POST
--header "Content-Type: application/x-www-form-urlencoded"
--header "Authorization: Basic {BASIC_TOKEN}"
--data "grant_type=client_credentials &client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}" |
Get your Merchants Bearer Token
Step 1. Set up your Partner OAuth flow with PayHQ by sending us your selected business name, an image url for your business with a square format, and the callback URI to your Merrco or Payfirma point of contact.
...
| Code Block |
|---|
Step 3.
curl https://auth.payfirma.com/oauth/token?grant_type=authorization_code&code=Grf5pV&redirect_uri=https%3A%2F%2Fwww.example.com&state=xyzABC123
--request POST
--header "Content-Type: application/x-www-form-urlencoded"
--header "Authorization: Basic {BASIC_TOKEN}"
Step 4.
{"access_token":"{BEARER_TOKEN}","token_type": "Bearer","refresh_token": "955d8714-f1d6-49d6-830a-2d221631a2b3", "expires_in": 1199, "merchant_id": "01234abcde", "scope": "invoice ecom"}
Step 5.
curl https://auth.payfirma.com/oauth/token?grant_type=refresh_token&refresh_token=41c128f2-b2e2-4d85-9443-b6e37d02a482&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}
--request POST
--header "Content-Type: application/x-www-form-urlencoded" |
Simple Transactions
Sales and Authorizations can be completed on their own, while a Capture transaction requires an Authorization transaction and a Refund requires either a Sale or Capture.
Charge a card
Step 1. Use the Bearer Token as your Authorization header and make sure to provide all the card parameters required for a regular sale transaction along with the different request URL.
| Code Block |
|---|
curl https://apigateway.payfirma.com/transaction-service/sale
--request POST
--header "Content-Type: application/json"
--header "Authorization: Bearer{BEARER_TOKEN}"
--data "{
"amount": 10.99,
"currency": "CAD",
"card_expiry_month": 11,
"card_expiry_year":16,
"card_number": "4111111111111111",
"cvv2": 595
}" |
Authorize a hold and then capture the payment
Step 1. Use the Bearer Token as your Authorization header and make sure to provide all the card parameters required for a regular sale transaction along with the different request URL. The hold will stay on the card for between 5-30 business days depending on the policy of the cardholder’s bank.
...
| Code Block |
|---|
Step 1
curl https://apigateway.payfirma.com/transaction-service/authorize
--request POST
--header "Content-Type: application/json"
--header "Authorization: Bearer {BEARER_TOKEN}"
--data "{
"amount": 10.99,
"currency": "CAD",
"card_expiry_month": 11,
"card_expiry_year": 16,
"card_number":"4111111111111111",
"cvv2": 595
}"
Step 2
curl https://apigateway.payfirma.com/transaction-service/capture/{ID}
--request POST
--header "Content-Type: application/json"
--header "Authorization: Bearer {BEARER_TOKEN}"
--data "{"amount": 10.99,}" |
Refund a payment
Option 1. Log into PayHQ and select My Transactions to view the complete list of transaction available for review. With each transaction, you have the control to refund the transaction and send a receipt for the refund to the email of your preference.
...
| Code Block |
|---|
curl " https://apigateway.payfirma.com/transaction-service/refund/{ID} "
--header "Content-Type: application/json"
--header "Authorization: Bearer {BEARER_TOKEN}"
--data "{"amount": 10.99,}"
curl
--include
--request POST
--header "Content-Type: application/json"
--header "Authorization: Bearer {BEARER_TOKEN}"
--data-binary "{ "amount": 10.99, "test_mode": true}"
"https://apigateway.payfirma.com/transaction-service/refund/1234567" |
Encrypt credit card as a token
The Payfirma Card Encryption Javascript library generates a secure and encrypted card token to be used with any of our transaction methods.
How to use this library
This library was developed specifically for client use.
...
| Code Block |
|---|
let publicEncryptionKey = "2d2d2d2d2d424547494e205055424c4943204b45592d2d2";
let cardNumber = "1234567890123456";
let cardMonth = "01";
let cardYear = "23";
let cardCvv2 = "045"
let encryptedCard = window.PayfirmaCardEncryption(publicEncryptionKey, cardNumber, cardMonth, cardYear, cardCvv2);
let transactionObject = {
amount: 0.01,
currency: "CAD",
token: encryptedCard,
email: "goku.son@payfirma.com",
first_name: "Goku",
last_name: "Son",
company: "Capsule Corporation",
telephone: "123-456-7890"
}; |
Future Payments
The Customer and Transaction Services can be used together to store cards and make payments on those stored cards.The Customer and Plan Services can be used together to set up recurring payment plans called subscriptions.
Storing a credit card
Step 1. Create a customer with all the key details that you want to store in the PayHQ database.
...
| Code Block |
|---|
Step 1.
curl "https://apigateway.payfirma.com/customer-service/customer"
--request POST
--header "Content-Type: application/json"
--header "Authorization: Bearer {BEARER_TOKEN}"
--data "{
"email": "brandon@stark.com",
"first_name": "Brandon",
"last_name": "Stark",
"company": "Payfirma",
"bcc_emails": "john.snow@stark.com",
"telephone": "1234567891",
"address1": "No. 1 Road",
"address2": "Street 2",
"city": "Vancouver",
"province": "BC",
"country": "Canada",
"postal_code": "V6E 1B2",
"custom_id": "Internal456"}"
Step 2.
curl "https://apigateway.payfirma.com/customer-service/customer/{CUSTOMER_LOOKUP_ID/card/"
--request POST
--header "Content-Type: application/json"
--header "Authorization: Bearer {BEARER_TOKEN}"
--data {
"card_expiry_month": 11,
"card_expiry_year": 16,
"card_number": "4111111111111111",
"cvv2": "595",
"is_default": true,
"card_description":
"test card" } |
Making a payment on a stored card
Step 1. Use the Customer_Lookup_ID to make a payment with the default card.
...
| Code Block |
|---|
Step 1.
curl "https://apigateway.payfirma.com/customer-service/customer/{CUSTOMER_LOOKUP_ID/card/"
--request POST
--header "Content-Type: application/json"
--header "Authorization: Bearer {BEARER_TOKEN}"
--data " { "amount": 10.99,"currency": "CAD" }
Step 2.
curl "https://apigateway.payfirma.com/customer-service/customer/{CUSTOMER_LOOKUP_ID/card/{CARD_LOOKUP_ID}/"
--request POST
--header "Content-Type: application/json"
--header "Authorization: Bearer {BEARER_TOKEN}"
--data " { "amount": 10.99,"currency": "CAD"} |
Subscribe a customer with a stored card
Step 1. Create a plan with the key payment details.
...
| Code Block |
|---|
Step 1.
curl " https://apigateway.payfirma.com/plan-service/plan/"
--request POST
--header "Content-Type: application/json"
--header "Authorization: Bearer {BEARER_TOKEN}"
--data " {
"name": "Sample Daily Plan",
"amount": 10.99,
"currency": "CAD",
"frequency": "DAILY",
"number_of_payments": 10,
"send_receipt": false
}"
Step 3.
curl " https://apigateway.payfirma.com/customer-service/customer/{CUSTOMER_LOOKUP_ID}/subscription "
--request POST
--header "Content-Type: application/json"
--data {
"plan_lookup_id": "{PLAN_LOOKUP_ID}",
"card_lookup_id": "{CARD_LOOKUP_ID}",
"amount": 10.99,
"start_date": 1467760023000,
"email": "brandon@stark.com"
"description": "My test subscription"
} ” |
Reporting
Transaction reporting can be accessed through the PayHQ web application or through the PayHQ API.
Get your transactions
Option 1. Log into PayHQ and select "My Transactions" to view the complete list of transaction available for review. There is also the option to export the transaction list to a .csv file.
...
| Code Block |
|---|
curl " https://apigateway.payfirma.com/transaction-service/transaction?limit=10000"
--request POST
--header "Authorization: Bearer {BEARER_TOKEN}" |
Get your merchant's transactions
Request the full list of transactions according to whatever parameters you specify and please note that the account data will be based off the Bearer token.
| Code Block |
|---|
curl " https://apigateway.payfirma.com/transaction-service/transaction?limit=10000"
--request POST
--header "Authorization: Bearer {BEARER_TOKEN}" |
Glossary
Authorization is a financial transaction that places a hold on the credit or debit card for the amount you specify. This hold will last 10-20 business days depending on the cardholder’s bank policy. Please see Capture for how to receive money from this hold. This term can also refer to the class of token for the Basic and Bearer Tokens.
...