Guides

This is a collection of some of the most common use cases for payFURL. If you're looking to get started, this is the place to come.

Accepting a payment with a card

curl

curl -d '{"Amount":"20", "ProviderId":"a26c371f94f640daadd228ec8e9da8ed", "PaymentInformation" : {"CardNumber" : "4111111111111111", "ExpiryDate" : "12/22", "Ccv" : "123"}}' \
     -H "Content-Type: application/json" \
     -H "x-secretkey: <secret_key>" \
     -X POST https://sandbox-api.payfurl.com/charge/card

C#

var chargeData = new NewChargeCard
{
  Amount = 20,
  ProviderId = "a26c371f94f640daadd228ec8e9da8ed",
  PaymentInformation = new CardRequestInformation
  {
    CardNumber = "4111111111111111",
    ExpiryDate = "12/22",
    Ccv = "123"
  }
};

var svc = new payfurl.sdk.Charge();
var result = svc.CreateWithCard(charge);

PHP

<?
  $svc = new Charge();

  $result = $svc->CreateWithCard([
      "Amount" => 15.5,
      "Currency" => "AUD",
      "Reference" => "123",
      "ProviderId" => $this->CardProviderId,
      "PaymentInformation" => [
          "CardNumber" => "4111111111111111",
          "ExpiryDate" => "10/30",
          "Ccv" => "123",
          "Cardholder" => "Test Cardholder"]]);
?>

Java

CardRequestInformation cardRequestInformation = new CardRequestInformation.Builder()
            .withCardNumber("4111111111111111")
            .withExpiryDate("12/22")
            .withCcv("123")
            .build();

NewChargeCard newChargeCard = new NewChargeCardRequest.Builder()
            .withAmount(BigDecimal.valueOf(20))
            .withProviderId("a26c371f94f640daadd228ec8e9da8ed")
            .withPaymentInformation(cardRequestInformation)
            .build();

ChargeApi chargeApi = payFurlClient.getChargeApi();
ChargeData chargeData = chargeApi.createWithCard(newChargeCard);

For all parameters to the API, see Create Charge

Accepting a payment with a token

First, use the Client SDK to securely convert the payment details to a payment token. You can then use that token to accept a payment.

curl

curl -d '{"Amount":"20", "Token":"5db53c06443c8f28c0cba6e5"}' \
    -H "Content-Type: application/json" \
    -H "x-secretkey: <secret_key>" \
    -X POST https://sandbox-api.payfurl.com/charge/token

C#

var charge = new NewChargeToken
{
    Amount = 20,
    Token = "5db53c06443c8f28c0cba6e5"
};

var svc = new payfurl.sdk.Charge();
var result = svc.CreateWithToken(charge);

PHP

<?
$svc = new Charge();

$result = $svc->CreateWithToken([
  "Amount" => 15.5,
  "Token" => "5db53c06443c8f28c0cba6e5"]);
?>

Java

NewChargeToken newChargeToken = new NewChargeToken.Builder()
          .withAmount(BigDecimal.valueOf(20))
          .withToken("5dc5cfbaec7c4d057cb00482")
          .build();

ChargeApi chargeApi = payFurlClient.getChargeApi();
ChargeData chargeData = chargeApi.createWithToken(newChargeToken);

For all parameters to the API, see Create Charge with a Token

Accepting a payment with a bank account

curl

curl -d '{"Amount":"20", "ProviderId":"a26c371f94f640daadd228ec8e9da8ed", "BankPaymentInformation" : {"BankCode" : "012-003", "AccountNumber" : "11111", "AccountName" : "Bank Account"}}' \
     -H "Content-Type: application/json" \
     -H "x-secretkey: <secret_key>" \
     -X POST https://sandbox-api.payfurl.com/charge/bank_account

C#

var chargeData = new NewChargeBankPayment
{
  Amount = 20,
  ProviderId = "a26c371f94f640daadd228ec8e9da8ed",
  BankPaymentInformation = new BankPaymentInformationData
  {
    BankCode = "012-003",
    AccountNumber = "11111",
    AccountName = "Bank Account"
  }
};

var svc = new payfurl.sdk.Charge();
var result = svc.CreateWithBankAccount(charge);

PHP

<?
  $svc = new Charge();

  $result = $svc->CreateWithBankAccount([
      "Amount" => 15.5,
      "ProviderId" => $this->CardProviderId,
      "BankPaymentInformation" => [
          "BankCode" => "012-003",
          "AccountNumber" => "11111",
          "AccountName" => "Bank Account"]]);
?>

Java

BankPaymentInformation bankAccountRequestInformation = new BankPaymentInformation.Builder()
            .withBankCode("012-003")
            .withAccountNumber("11111")
            .withAccountName("Bank Account")
            .build();

NewChargeBankPaymentRequest newChargeBankAccount = new NewChargeBankPaymentRequest.Builder()
            .withAmount(BigDecimal.valueOf(20))
            .withProviderId("a26c371f94f640daadd228ec8e9da8ed")
            .withBankPaymentInformation(bankAccountRequestInformation)
            .build();

ChargeApi chargeApi = payFurlClient.getChargeApi();
ChargeData chargeData = chargeApi.createWithBankAccount(newChargeBankAccount);

For all parameters to the API, see Create Charge with a bank account

Creating a Customer

If you want to accept payments for the same payment details more than once, it's best to create a customer.

First, use the Client SDK to securely convert the payment details to a payment token. You can then use that token to create a customer:

curl

curl -d '{"FirstName":"John", "LastName":"Doe", "Reference":"123", "Token":"5db53c06443c8f28c0cba6e5"}' \
    -H "Content-Type: application/json" \
    -H "x-secretkey: <secret_key>" \
    -X POST https://sandbox-api.payfurl.com/customer/token

C#

var customer = new NewCustomerToken
{
  FirstName = "John",
  LastName = "Doe",
  Reference = "123",
  Token = "5db53c06443c8f28c0cba6e5"
};

var svc = new payfurl.sdk.Charge();
var result = svc.CreateWithToken(charge);

PHP

<?
$svc = new Customer();

$result = $svc->CreateWithToken([
  "FirstName" => "John",
  "LastName" => "Doe",
  "Reference" => "123",
  "Token" => "5db53c06443c8f28c0cba6e5"]);
?>

Java

NewCustomerToken newCustomerToken = new NewCustomerToken.Builder()
  .withFirstName("John")
  .withLastName("Doe")
  .withReference("123")
  .withToken("5db53c06443c8f28c0cba6e5")
  .build();

CustomerApi customerApi = $config._code_java_var}.getCustomerApi();
CustomerData customerData = customerApi.createWithToken(newCustomerToken);

For all parameters to the API, see Create Customer

Accepting a Payment for a Customer

If you already have a customer, you can use that customer to accept a payment for that customer.

curl

curl -d '{"Amount":"20", "ProviderId":"7eeeb601-2992-486d-8dc9-f788eef26f95", "CustomerId":"95af2d87-36a6-499d-87c8-e887a3498f1e"}' \
    -H "Content-Type: application/json" \
    -H "x-secretkey: <secret_key>" \
    -X POST https://sandbox-api.payfurl.com/charge/customer

C#

var customer = new NewChargeCustomer
{
  Amount = 20,
  ProviderId = "7eeeb601-2992-486d-8dc9-f788eef26f95",
  CustomerId = "95af2d87-36a6-499d-87c8-e887a3498f1e"
};

var svc = new payfurl.sdk.Customer();
var result = svc.CreateWithCustomer(customer);

PHP

<?
$svc = new Charge();

$result = $svc->CreateWithCustomer([
    "Amount" => 20,
    "ProviderId" => "7eeeb601-2992-486d-8dc9-f788eef26f95",
    "CustomerId" => "95af2d87-36a6-499d-87c8-e887a3498f1e"]);
?>

Java

NewChargeCustomer newChargeCustomer = new NewChargeCustomer.Builder()
  .withAmount(BigDecimal.valueOf(20))
  .withProviderId("7eeeb601-2992-486d-8dc9-f788eef26f95")
  .withCustomerId("95af2d87-36a6-499d-87c8-e887a3498f1e")
  .build();

ChargeApi chargeApi = payFurlClient.getChargeApi();
ChargeData chargeData = chargeApi.createWithCustomer(newCustomerToken);

For all parameters to the API, see Create a Charge for a Customer

Creating a Payment Method

If you want to accept payments for the same payment details more than once but do not want to create a customer, you can create a payment method.

curl

curl -d '{"ProviderId":"a26c371f94f640daadd228ec8e9da8ed", "PaymentInformation" : {"CardNumber" : "4111111111111111", "ExpiryDate" : "12/22", "Ccv" : "123"}}' \
    -H "Content-Type: application/json" \
    -H "x-secretkey: <secret_key>" \
    -X POST https://sandbox-api.payfurl.com/payment_method/card

C#

var data = new NewPaymentMethod
{
  ProviderId = "a26c371f94f640daadd228ec8e9da8ed",
  PaymentInformation = new CardRequestInformation
  {
      CardNumber = "4111111111111111",
      ExpiryDate = "12/22",
      Ccv = "123"
  }
};

var svc = new payfurl.sdk.PaymentMethod();
var result = svc.CreateWithCard(data);

PHP

<?
$svc = new PaymentMethod();

$result = $svc->CreatePaymentMethodWithCard([
  "ProviderId" => "a26c371f94f640daadd228ec8e9da8ed",
  "PaymentInformation" => [
      "CardNumber" => "4111111111111111",
      "ExpiryDate" => "10/30",
      "Ccv" => "123",
      "Cardholder" => "Test Cardholder"]]);
?>

Java

CardRequestInformation cardRequestInformation = new CardRequestInformation.Builder()
  .withCardNumber("4111111111111111")
  .withExpiryDate("12/22")
  .withCcv("123")
  .build();
NewPaymentMethod newPaymentMethod = new NewPaymentMethod.Builder()
  .withProviderId("a26c371f94f640daadd228ec8e9da8ed")
  .withPaymentInformation(cardRequestInformation)
  .build();

PaymentMethodApi paymentMethodApi = payFurlClient.getPaymentMethodApi();
PaymentMethodData paymentMethodData = paymentMethodApi.createPaymentMethodWithCard(newPaymentMethod);

For all parameters to the API, see Create Payment Method

Creating a Payment Method with a token

If you want to accept payments for the same payment details more than once but do not want to create a customer, you can create a payment method with a token.

curl

curl -d '{"Token" : "dc16e22be13246809c9f05c1a4bf92fa"}' \
    -H "Content-Type: application/json" \
    -H "x-secretkey: <secret_key>" \
    -X POST https://sandbox-api.payfurl.com/payment_method/token

C#

var data = new NewPaymentMethodToken
{
  Token : "dc16e22be13246809c9f05c1a4bf92fa"
};

var svc = new payfurl.sdk.PaymentMethod();
var result = svc.CreateWithToken(data);

PHP

<?
$svc = new PaymentMethod();

$result = $svc->CreateWithToken(["Token" => "dc16e22be13246809c9f05c1a4bf92fa"]);
?>

Java

NewPaymentMethodToken newPaymentMethodToken = new NewPaymentMethodToken.Builder()
  .withToken("dc16e22be13246809c9f05c1a4bf92fa")
  .build();

PaymentMethodApi paymentMethodApi = payFurlClient.getPaymentMethodApi();
PaymentMethodData paymentMethodData = paymentMethodApi.createPaymentMethodWithToken(newPaymentMethodToken);

For all parameters to the API, see Create Payment Method With A Token

Accepting a payment for a Payment Method

If you already have a payment method, you can use that payment method to accept a payment for that payment method.

curl

curl -d '{"Amount":"20", "PaymentMethodId":"154d5c8940db4d76ba9334fb44241aa4", "Currency":"AUD"}' \
    -H "Content-Type: application/json" \
    -H "x-secretkey: <secret_key>" \
    -X POST https://sandbox-api.payfurl.com/charge/payment_method

C#

var paymentMethod = new NewChargePaymentMethod
{
    Amount = 20,
    PaymentMethodId = "154d5c8940db4d76ba9334fb44241aa4",
    Currency = "AUD"
};

var svc = new payfurl.sdk.Charge();
var result = svc.CreateWithPaymentMethod(paymentMethod);

PHP

<?
$svc = new Charge();

$result = $svc->CreateWithPaymentMethod([
  "Amount" => 20,
  "PaymentMethodId" => "154d5c8940db4d76ba9334fb44241aa4",
  "Currency" => "AUD"]);
?>

Java

NewChargePaymentMethod newChargePaymentMethod = new NewChargeCustomer.Builder()
  .withAmount(BigDecimal.valueOf(20))
  .withCurrency("AUD")
  .withPaymentMethodId("154d5c8940db4d76ba9334fb44241aa4")
  .build();

ChargeApi chargeApi = payFurlClient.getChargeApi();
ChargeData chargeData = chargeApi.createWitPaymentMethod(newChargePaymentMethod);

For all parameters to the API, see Create a Charge for a Payment Method

Refund

If payment status is SUCCESS or PARTIAL_REFUND you can refund this payment by using the Refund method.

curl

curl --location --request DELETE 'https://sandbox-api.payfurl.com/refund/b59efd7afd9949fbb1d5aed4cf83aedb' \
-H 'x-secretkey: <secret_key>' \
-H 'Content-Type: application/json'

C#

var svc = new payfurl.sdk.Charge();

var chargeRefund = new NewRefund
{
  ChargeId = "b59efd7afd9949fbb1d5aed4cf83aedb"
};

var refundData = svc.Refund(chargeRefund);

PHP

<?
$svc = new Charge();
$svc->Refund(["ChargeId" => "b59efd7afd9949fbb1d5aed4cf83aedb"]);
?>

Java

ChargeApi chargeApi = payFurlClient.getChargeApi();
NewRefund newRefund = new NewRefund.Builder()
      .withChargeId("b59efd7afd9949fbb1d5aed4cf83aedb")
      .build();
ChargeData chargeData = chargeApi.refund(newRefund);

Authorise & Capture

Any payment request could have a Capture parameter (by default Capture = true) and you can decide whether you want to have payment captured immediately or not. If payment was created with Capture = false it means that status of this payment is Authorised. You can complete this payment by using the Capture method.

curl

curl -d '{"Amount":"20", "Currency" : "USD", "CustomerId":"95af2d87-36a6-499d-87c8-e887a3498f1e", "Capture": false}' \
-H "Content-Type: application/json" \
-H "x-secretkey: <secret_key>" \
-X POST https://sandbox-api.payfurl.com/charge/customer

curl --location --request POST 'https://sandbox-api.payfurl.com/charge/b59efd7afd9949fbb1d5aed4cf83aedb' \
-H 'x-secretkey: <secret_key>' \
-H 'Content-Type: application/json' \
-d '{
    "Amount": 20
}'

C#

var customer = new NewChargeCustomer
{
Amount = 20,
CustomerId = "95af2d87-36a6-499d-87c8-e887a3498f1e",
Currency = "USD",
Capture = false
};

  var svc = new payfurl.sdk.Charge();
  var result = svc.CreateWithCustomer(customer);

  var chargeCapture = new NewChargeCapture
  {
      Amount = 20
  };

  var capturedData = svc.Capture(result.ChargeId, chargeCapture);

PHP

<?
$svc = new Charge();

      $result = $svc->CreateWithCustomer([
          "Amount" => 20,
          "Currency" => "USD",
          "Capture" => false,
          "CustomerId" => "95af2d87-36a6-499d-87c8-e887a3498f1e"]);

      $chargeId = $result["ChargeId"];
      $svc->Capture([
          "Amount" => 20,
          "ChargeId" => $chargeId
      ]);
?>

Java

NewChargeCustomer newChargeCustomer = new NewChargeCustomer.Builder()
.withAmount(BigDecimal.valueOf(20))
.withCurrency("USD")
.withCapture(false)
.build();

  ChargeApi chargeApi = payFurlClient.getChargeApi();
  ChargeData chargeDataWithCustomer = chargeApi.createWithCustomer(newCustomerToken);

  NewChargeCapture newChargeCapture = new NewChargeCapture.Builder()
          .withAmount(BigDecimal.valueOf(20))
          .build();
  ChargeData chargeData = chargeApi.captureCharge(chargeDataWithCustomer.getChargeId(), newChargeCapture);

Void

If status of payment is Authorised you can cancel it by the Void method.

curl

curl -d '{"Amount":"20", "Currency" : "USD", "CustomerId":"95af2d87-36a6-499d-87c8-e887a3498f1e", "Capture": false}' \
-H "Content-Type: application/json" \
-H "x-secretkey: <secret_key>" \
-X POST https://sandbox-api.payfurl.com/charge/customer

curl --location --request DELETE 'https://sandbox-api.payfurl.com/charge/b59efd7afd9949fbb1d5aed4cf83aedb/void' \
-H 'x-secretkey: <secret_key>' \
-H 'Content-Type: application/json'

C#

var customer = new NewChargeCustomer
{
Amount = 20,
CustomerId = "95af2d87-36a6-499d-87c8-e887a3498f1e",
Currency = "USD",
Capture = false
};

  var svc = new payfurl.sdk.Charge();
  var result = svc.CreateWithCustomer(customer);

  svc.Void(result.ChargeId);

PHP

<?
$svc = new Charge();

      $result = $svc->CreateWithCustomer([
          "Amount" => 20,
          "Currency" => "USD",
          "Capture" => false,
          "CustomerId" => "95af2d87-36a6-499d-87c8-e887a3498f1e"]);

      $chargeId = $result["ChargeId"];
      $svc->Void([
          "ChargeId" => $chargeId
      ]);
?>

Java

NewChargeCustomer newChargeCustomer = new NewChargeCustomer.Builder()
.withAmount(BigDecimal.valueOf(20))
.withCurrency("USD")
.withCapture(false)
.build();

  ChargeApi chargeApi = payFurlClient.getChargeApi();
  ChargeData chargeData = chargeApi.createWithCustomer(newCustomerToken);

  chargeApi.voidCharge(chargeData.getChargeId());

Search for Transactions

You may want to check whether a transaction has succeeded or search for past transactions for a customer.

curl

curl -H "Content-Type: application/json" \
    -H "x-secretkey: <secret_key>" \
    -X GET https://sandbox-api.payfurl.com/charge?reference=123

C#

var search = new ChargeSearch
{
Reference = "123"
};

  var svc = new payfurl.sdk.Charge();
  var result = svc.Search(search);

PHP

<?
$svc = new Charge();

  $result = $svc->Search([
      "Reference" => "123"]);
?>

Java

ChargeSearch chargeSearch = new ChargeSearch.Builder()
.withReference("123")
.build();

    ChargeApi chargeApi = payFurlClient.getChargeApi();
    ChargeList chargeData = chargeApi.search(chargeSearch);

For all parameters to the API, see Search for Transactions

Search for Customers

You may want to search for a specific customer based on email address or name.

curl

curl -H "Content-Type: application/json" \
    -H "x-secretkey: <secret_key>" \
    -X GET https://sandbox-api.payfurl.com/customer?email=john.doe@gmail.com

C#

var search = new CustomerSearch
{
Email = "john.doe@gmail.com"
};

  var svc = new payfurl.sdk.Customer();
  var result = svc.Search(search);

PHP

<?
$svc = new Customer();

  $result = $svc->Search([
      "Email" => "john.doe@gmail.com"]);
?>

Java

CustomerSearch customerSearch = new CustomerSearch.Builder()
.withEmail("john.doe@gmail.com")
.build();

  CustomerApi customerApi = payFurlClient.getCustomerApi();
  CustomerList chargeData = customerApi.search(customerSearch);

For all parameters to the API, see Search for Customers