Get Sandbox Access

Paybase Developer Centre

OverviewAPI GuidesGetting StartedRecipesGig Economy PlatformsSharing Economy PlatformsMarketplacesBlockchain BusinessesEscrowSandboxRolesRulesDue DiligenceCustomersAccountsBank AccountsCardsTransactionsIntroductionInboundGetting money into the systemTransaction ReferenceAccount ReferenceInternalOutboundEscrowSplit PaymentsRefundsStrong Customer Authentication3D Secure AuthenticationIntroductionCreate a cardCreate a transactionDocument UploadStatementsWebhooksErrorsPQLAPI ReferenceAccountCreate an accountRetrieve an accountTransition account statusList all accountsAnnotate an accountDelete annotation from an accountTag an accountDelete tag from an accountBank AccountCreate a bank accountRetrieve a bank accountUpdate a bank accountTransition bank account statusList all bank accountsAnnotate a bank accountDelete annotation from a bank accountTag a bank accountDelete tag from a bank accountCardCreate a cardRetrieve a cardUpdate a cardTransition card statusList all cardsAnnotate a cardDelete annotation from a cardTag a cardDelete tag from a cardCardholderCreate a cardholderRetrieve a cardholderUpdate a cardholderTransition cardholder statusList all cardholdersAnnotate a cardholderDelete annotation from a cardholderTag a cardholderDelete tag from a cardholderCreate an authentication tokenCheckCreate a checkCustomerIndividual CustomerCreate a customerRetrieve a customerUpdate a customerSole TraderCreate a customerRetrieve a customerUpdate a customerOrganisationCreate a CustomerRetrieve a CustomerUpdate a CustomerIncorporated BusinessCreate a customerRetrieve a customerUpdate a customerBusiness PersonAdd a business personRetrieve a business personUpdate a business personDelete a business personRetrieve a customerTransition state of a customerList all customersAnnotate a customerDelete annotation from a customerTag a customerRemove tag from a customerCreate an authentication tokenTouch a customerDocumentCreate a documentRetrieve a documentList Document TypesReferenceRetrieve a referenceStatementRetrieve a statementStatusRetrieve API statusTransactionCreate inbound transactionCreate internal transactionCreate outbound transactionRetrieve a transactionTransition transaction statusList all transactionsAnnotate a transactionDelete annotation from a transactionTag a transactionDelete tag from a transaction
API version: ba085a6

Transaction Refunds

Refunding a Transaction

To apply a refund to a transaction use the options field when transitioning a transaction. The toStateId should always be ADJUSTED. An adjustment option should be used with an adjustmentAmount and reason with the adjustmentAmount being a positive value with the amounted denoted in the smalled currency unit (e.g in pennies for GBP, or cents for EUR).

An example request body:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import { v1 } from '@paybase/client';

const client = v1('<- API Key ->', { sandbox: true });

const { accessToken } = await client.createCustomerAuthenticationToken({
  id: "<- Sending Customer ID ->"
});

const result = await client.transitionTransaction({
  id: "tx/2010d1ce-d46b-4ee8-bec2-cc6d4430a5ac",
  toStateId: "ADJUSTED",
  options: {
    adjustment: {
      adjustmentAmount: "500",
      reason: "sale item was not as described"
    }
  }
}, { apiKey: accessToken });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import json
import requests

requests.patch(
  "https://api-json.sandbox.paybase.io/v1/tx/tx/2010d1ce-d46b-4ee8-bec2-cc6d4430a5acParams: id/state",
  data = json.dumps({
    "toStateId": "ADJUSTED",
    "options": {
      "adjustment": {
        "adjustmentAmount": "500",
        "reason": "sale item was not as described"
      }
    }
  }),
  headers = {
    "X-Token": "<... snip ...>",
    "Content-Type": "application/json"
  }
).json()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
$client = new \GuzzleHttp\Client();
$client->request(
  "patch",
  "https://api-json.sandbox.paybase.io/v1/tx/tx/2010d1ce-d46b-4ee8-bec2-cc6d4430a5acParams: id/state",
  [
    "body" => "{
      \"toStateId\": \"ADJUSTED\",
      \"options\": {
        \"adjustment\": {
          \"adjustmentAmount\": \"500\",
          \"reason\": \"sale item was not as described\"
        }
      }
    }",
    "headers" => [
      "X-Token" => "<... snip ...>",
      "Content-Type" => "application/json",
    ]
  ]
);

1
2
3
4
5
6
7
8
9
10
11
12
13
curl -X PATCH \
"https://api-json.sandbox.paybase.io/v1/tx/tx/2010d1ce-d46b-4ee8-bec2-cc6d4430a5acParams: id/state"  -H "X-Token: <... snip ...>" \
  -H "Content-Type: application/json" \
  -d '{
    "toStateId": "ADJUSTED",
    "options": {
      "adjustment": {
        "adjustmentAmount": "500",
        "reason": "sale item was not as described"
      }
    }
  }'

Any fee that was applied to the transaction will be also be adjusted and the refunded fee amount will be proportional to the total amount refunded. e.g. if a 10% fee was applied to a £100 transaction and £50 is eventually refunded, 10% of the £50 i.e £5 of the initial £10 fee will also be refunded.

Refunding a Single Adjustment

Where a transaction has multiple adjustments, you can also refund a specific adjustment instead of the entire transaction. For example, if you have created a transaction charging a buyer £100 of which £98 is sent to the seller and £2 is charged as platform fee, the transaction will have 2 adjustments of £98 and £2 respectively. If you now wish to refund the buyer but keep the £2 platform fee, you can refund only the £98 adjustment by providing the id of that adjustment in the options attribute. Not providing an adjustmentAmount will default to refunding 100% of the value of the adjustment i.e. £98 in this case. If for example you wished to only refund £50 instead, you can specify this in the adjustmentAmount. You may also provide an optional reason for increased granularity.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import { v1 } from '@paybase/client';

const client = v1('<- API Key ->', { sandbox: true });

const { accessToken } = await client.createCustomerAuthenticationToken({
  id: "<- Sending Customer ID ->"
});

const result = await client.transitionTransaction({
  id: "tx/2010d1ce-d46b-4ee8-bec2-cc6d4430a5ac",
  toStateId: "ADJUSTED",
  options: {
    adjustment: {
      adjustmentAmount: "9800",
      adjustmentId: "tx/d99f9a87-fe53-4574-8261-30f75e44a587",
      reason: "cancelled orderd, refunded minus fee"
    }
  }
}, { apiKey: accessToken });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import json
import requests

requests.patch(
  "https://api-json.sandbox.paybase.io/v1/tx/tx/2010d1ce-d46b-4ee8-bec2-cc6d4430a5acParams: id/state",
  data = json.dumps({
    "toStateId": "ADJUSTED",
    "options": {
      "adjustment": {
        "adjustmentAmount": "9800",
        "adjustmentId": "tx/d99f9a87-fe53-4574-8261-30f75e44a587",
        "reason": "cancelled orderd, refunded minus fee"
      }
    }
  }),
  headers = {
    "X-Token": "<... snip ...>",
    "Content-Type": "application/json"
  }
).json()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
$client = new \GuzzleHttp\Client();
$client->request(
  "patch",
  "https://api-json.sandbox.paybase.io/v1/tx/tx/2010d1ce-d46b-4ee8-bec2-cc6d4430a5acParams: id/state",
  [
    "body" => "{
      \"toStateId\": \"ADJUSTED\",
      \"options\": {
        \"adjustment\": {
          \"adjustmentAmount\": \"9800\",
          \"adjustmentId\": \"tx/d99f9a87-fe53-4574-8261-30f75e44a587\",
          \"reason\": \"cancelled orderd, refunded minus fee\"
        }
      }
    }",
    "headers" => [
      "X-Token" => "<... snip ...>",
      "Content-Type" => "application/json",
    ]
  ]
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -X PATCH \
"https://api-json.sandbox.paybase.io/v1/tx/tx/2010d1ce-d46b-4ee8-bec2-cc6d4430a5acParams: id/state"  -H "X-Token: <... snip ...>" \
  -H "Content-Type: application/json" \
  -d '{
    "toStateId": "ADJUSTED",
    "options": {
      "adjustment": {
        "adjustmentAmount": "9800",
        "adjustmentId": "tx/d99f9a87-fe53-4574-8261-30f75e44a587",
        "reason": "cancelled orderd, refunded minus fee"
      }
    }
  }'