Metadata | Payroc | Documentation

Metadata is a feature of our API that you can use to attach additional information to a resource without changing how the resource behaves. You can use metadata to store small pieces of contextual data that aren’t part of the standard API fields, for example, who created the resource or how it maps to your internal systems.

Send your metadata as a set of key-value pairs for your own reference, auditing, or troubleshooting. When you retrieve a resource with attached metadata, we echo back the information exactly as you provided it.

What we do with metadata

We don’t consume metadata or use it for any internal purposes, but we do:

Validate its structure to make sure that it contains key-value pairs.
Encrypt it and store it with the resource that you link it to.
Return it when you retrieve the resource that it’s attached to.

Metadata best practices

Important: Never send sensitive information in metadata, for example, customer information, payment card details, or API keys.

Apply the following best practices when you add metadata to your requests:

Use unique key names.
Always validate your integration. If you send metadata in the wrong format, we reject the whole request and return a 400 error.
Never display metadata in a customer-facing user interface.

How to add metadata to your request

If you send a request that supports metadata, send the metadata object with a series of key-value pairs. You should be aware of the following constraints:

You can send up to 20 unique key-value pairs.
We accept keys that are String format with a maximum of 50 characters.
We accept values that are String format with a maximum of 1024 characters.
You can’t send nested JSON objects.

Some requests support adding metadata to more than one resource. Our worked examples below cover how to add metadata to one resource in a request, and also how to add metadata to two resources in one request.

Worked example 1 - single resource in a request

I’m integrating against the Create Event Subscription method. It would be useful to indicate the name of the person who is responsible for handling the event if it is fired, as the standard API fields only return the contact’s email address.

To do this, I’m going to add a responsiblePerson key-value pair to the event subscription.

Request

POST

/v1/event-subscriptions

1 using Payroc;
2 using System.Threading.Tasks;
3 using Payroc.Notifications.EventSubscriptions;
4 using System.Collections.Generic;
5 
6 namespace Usage;
7 
8 public class Example
9 {
10     public async Task Do() {
11         var client = new BasePayrocClient(
12             clientOptions: new ClientOptions {
13                 Environment = PayrocEnvironment.Production
14             }
15         );
16 
17         await client.Notifications.EventSubscriptions.CreateAsync(
18             new CreateEventSubscriptionsRequest {
19                 IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
20                 Body = new EventSubscription {
21                     Enabled = true,
22                     EventTypes = new List<string>(){
23                         "processingAccount.status.changed",
24                     }
25                     ,
26                     Notifications = new List<Notification>(){
27                         new Notification(
28                             new Webhook {
29                                 Secret = "aBcD1234eFgH5678iJkL9012mNoP3456",
30                                 SupportEmailAddress = "[email protected]",
31                                 Uri = "https://my-server/notification/endpoint"
32                             }
33                         ),
34                     }
35                     ,
36                     Metadata = new Dictionary<string, object?>(){
37                         ["responsiblePerson"] = "Jane Doe",
38                     }
39 
40                 }
41             }
42         );
43     }
44 
45 }

Try it

Worked example 2 - multiple resources in one request

I’m integrating against the Create Funding Instruction method, which creates a funding instruction and links recipients to it. It would be useful for me to add the following metadata:

Name of the person who created the funding instruction for audit purposes.
Name of the recipient who is receiving the funds.

To do this, I’m going to add an instructionCreatedBy key-value pair to the funding instruction, and I’m going to add a supplier key-value pair to the recipient object.

Request

POST

/v1/funding-instructions

1 using Payroc;
2 using System.Threading.Tasks;
3 using Payroc.Funding.FundingInstructions;
4 using System.Collections.Generic;
5 
6 namespace Usage;
7 
8 public class Example
9 {
10     public async Task Do() {
11         var client = new BasePayrocClient(
12             clientOptions: new ClientOptions {
13                 Environment = PayrocEnvironment.Production
14             }
15         );
16 
17         await client.Funding.FundingInstructions.CreateAsync(
18             new CreateFundingInstructionsRequest {
19                 IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
20                 Body = new Instruction {
21                     Merchants = new List<InstructionMerchantsItem>(){
22                         new InstructionMerchantsItem {
23                             MerchantId = "4525644354",
24                             Recipients = new List<InstructionMerchantsItemRecipientsItem>(){
25                                 new InstructionMerchantsItemRecipientsItem {
26                                     FundingAccountId = 123,
27                                     PaymentMethod = InstructionMerchantsItemRecipientsItemPaymentMethod.Ach,
28                                     Amount = new InstructionMerchantsItemRecipientsItemAmount {
29                                         Value = 120000,
30                                         Currency = InstructionMerchantsItemRecipientsItemAmountCurrency.Usd
31                                     },
32                                     Metadata = new Dictionary<string, string>(){
33                                         ["supplier"] = "IT Support Services",
34                                     }
35 
36                                 },
37                             }
38 
39                         },
40                     }
41                     ,
42                     Metadata = new Dictionary<string, string>(){
43                         ["instructionCreatedBy"] = "Jane Doe",
44                     }
45 
46                 }
47             }
48         );
49     }
50 
51 }

Try it